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Introduction 



This manual contains definitions of the Borland C++ classes, nonprivate 
class members, library routines, common variables, and common defined 
types for windows programming. 

If you're new to C or C++ programming, or if you're looking for informa- 
tion on the contents of the Borland C++ manuals, see the introduction in 
the User's Guide. 

Here is a summary of the chapters in this manual: 

Chapter 1 : The main function discusses arguments to main (including wild- 
card arguments), provides some example programs, and gives some 
information on Pascal calling conventions and the value that main returns. 

Chapter 2: Run-time functions is an alphabetical reference of all Borland 
C++ library functions. Each entry gives syntax, portability information, an 
operative description, and return values for the function, together with a 
reference list of related functions and examples of how the functions are 
used. 

Chapter 3: Global variables defines and discusses Borland C++'s global 
variables. You can use these to save yourself a great deal of programming 
time on commonly needed variables (such as dates, time, error messages, 
stack size, and so on). 

Chapter 4: The C++ iostreams provides a description of the classes that 
provide support for I/O in C++ programs. 

Chapter 5: Persistent stream classes and macros describes the persistent 
streams classes and macros. 

Chapter 6: The C++ container classes is a description of the C++ objects 
provided by Borland C++ to support data structures and data abstraction. 

Chapter 7: The C++ mathematical classes is a description of C++ 
mathematics using bed and complex classes. 

Chapter 8: Class diagnostic macros describes the classes and macros that 
support object diagnostics. 

Chapter 9: Run-time support describes functions and classes that let you 
control the way your program executes at run time in case the program 
runs out of memory or encounters some exception. 



introduction 



Chapter 10: C++ utility classes describes the C++ date, string, and time 
classes. 

Appendix A: Run-time library cross-reference contains an overview of the 
Borland C++ library routines and header files. The header files are listed 
alphabetically, and the library routines are grouped according to the tasks 
they commonly perform. 
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The main function 



Every C and C++ program must have a main function; where you place it is 
a matter of preference. Some programmers place main at the beginning of 
the file, others at the end. Regardless of its location, the following points 
about main always apply. 



Arguments to main 



Three parameters (arguments) are passed to main by the Borland C++ 
startup routine: argc, argv, and env. 

a argc, an integer, is the number of command-line arguments passed to 
main. 

u argv is an array of pointers to strings (char *[]). 

o argv[0] is the name of the program being run, exactly as the user typed 
it on the command line. 

e argp[l] points to the first string typed on the operating system 
command line after the program name. 

e argv[2] points to the second string typed after the program name. 

o argv[argc-l] points to the last argument passed to main. 

o argv[argc] contains NULL. 

□ env is also an array of pointers to strings. Each element of env[] holds a 
string of the form ENWAR= value. 

• ENVVAR is the name of an environment variable, such as PATH or 
COMSPEC. 

e value is the value to which ENVVAR is set, such as C:\APPS;C:\ 
TOOLS; (for PATH) or C:\DOS\COMMAND.COM for COMSPEC. 

If you declare any of these parameters, you must declare them exactly in the 
order given: argc, argv, env. For example, the following are all valid 
declarations of main's arguments: 
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int main() 

int main (int argc) /* legal but very unlikely */ 

int main (int argc, char * argv[]) 

int main (int argc, char * argv[], char * env[])] 

Refer to the environ The declaration int main ( int argc ) is legal, but it's very unlikely that you 
e [J tr y In Cnapter 3 would use argc in your program without also using the elements of argv. 

getem/ entries in j^ e argument env is also available through the global variable environ. 
Chapter 2 for more b o t> 

information. aT g C an( ^ ar g V are a i so available via the global variables _argc and _argv. 



. . Here is an example that demonstrates a simple way of using these 

An ex3mpie , , 

Droaram arguments passed to main: 

I* Program ARGS.C */ 
#include <stdio.h> 
iinclude <stdlib.h> 

int main (int argc, char *argv[], char *env[]) { 
int i; 

printf("The value of argc is Id \n\n", argc); 
printf( "These are the %& command-line arguments passed to" 
" main:\n\n" , argc) ; 

for (i = 0; i < argc; i++) 

printfC argv[%d]: %s\n", i, argv[i]); 

printf ("\nThe environment string(s) on this system are:\n\n"); 

for (i = 0; env[i] != NULL; i++) 

printf (" env[%d] : %s\n", i, env[i]); 
return 0; 
} 

Suppose you run ARGS.EXE at the OS/2 prompt with the following 
command line: 

C:> args first_arg "arg with blanks" 3 4 "last but one" stop! 

Note that you can pass arguments with embedded blanks by surrounding 
them with quotes, as shown by "argument with blanks" and "last but one" 
in this example command line. 

The output of ARGS.EXE (assuming that the environment variables are set 
as shown here) would then be like this: 

The value of argc is 7 

These are the 7 command-line arguments passed to main: 

argv[0] : args 
argv[l] : first_arg 
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argv[2]: args with blanks 

argv[3] : 3 

argv[4] : 4 

argv[5] : last but one 

argv[6] : stop! 

The environment string (s) on this system are: 



env[0] 
env [ 1 ] 
env[2] 
env [3] 
env[4] 
env [ 5 ] 
env [ 6 ] 
env [7] 
env[8] 
env[9] 
env [10 
env [11 
env [12 
env [13 



USER_INI=C : \OS2 \OS2 . INI 

SYSTEM_INI=C: \OS2\OS2SYS. INI 

OS2_SHELL=C : \OS2 \CMD. EXE 

AUTOSTART= PROGRAMS, TASKL I ST, FOLDERS 

RUNWORKPLACE=C : \OS2 \ PMSHELL . EXE 

COMSPEC=C: \OS2\CMD.EXE 

PATH=C:\OS2;C:\OS2\SYSTEM;C:\;C:\OS2\APPS; 

DPATH=C: \OS2;C:\OS2\ SYSTEM ;C:\;C:\OS2 \APPS ; 

PROMPT=$i[$p] 

HELP=C:\OS2\HELP; C:\OS2\HELP\TUTORIAL; 
: GLOSSARY=C:\OS2\HELP\GLOSS; 
: KEYS=ON 

: BOOKSHELF=C:\OS2\BOOK; 
: EPATH=C:\OS2\APPS 



Wildcard 
arguments 



Command-line arguments containing wildcard characters can be expanded 
to all the matching file names, much the same way DOS expands wildcards 
when used with commands like COPY. All you have to do to get wildcard 
expansion is to link your program with the WILDARGS.OBJ object file, 
which is included with Borland C++. 

Once WILDARGS.OBJ is linked into your program code, you can send 
wildcard arguments of the type *.* to your main function. The argument 
will be expanded (in the argv array) to all files matching the wildcard mask. 
The maximum size of the argv array varies, depending on the amount of 
memory available in your heap. 

If no matching files are found, the argument is passed unchanged. (That is, 
a string consisting of the wildcard mask is passed to main.) 

Arguments enclosed in quotes ("...") are not expanded. 



An example 
program 



The following commands compile the file ARGS.C and link it with the 
wildcard expansion module WILDARGS.OBJ, then run the resulting 
executable file ARGS.EXE: 



BCC ARGS.C WILDARGS.OBJ 
ARGS C:\BORLANDC\INCLUDE\*. H 



: .C" 



When you run ARGS.EXE, the first argument is expanded to the names of 
all the *.H files in your Borland C++ INCLUDE directory. Note that the 
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expanded argument strings include the entire path. The argument *.C is not 
expanded because it is enclosed in quotes. 

In the IDE, simply specify a project file (from the project menu) that 
contains the following lines: 

ARGS 
WILDARGS.OBJ 

Then use the Run I Arguments option to set the command-line parameters. 

■► If you prefer the wildcard expansion to be the default, modify your 

standard C7.LIB library files to have WILDARGS.OBJ linked automatically. 
To accomplish that, remove SETARGV and INITARGS from the libraries 
and add WILD ARGS. The following commands invoke the Turbo librarian 
(TLIB) to modify all the standard library files (assuming the current 
directory contains the standard C and C++ libraries and WILDARGS.OBJ): 

For more on TUB, tlib c2 -setargv -initargs +wildargs 

see the UserS Guide. tlib c2mt -setargv -initargs +wildargs 

Using -p (Pascal calling conventions) 

If you compile your program using Pascal calling conventions (described in 
detail in Chapter 2, "Language structure," in the Programmer's Guide), you 
must remember to explicitly declare main as a C type. Do this with the 
cdecl keyword, like this: 

int cdecl main(int argc, char* argv[], char* envp[]) 

The value main returns 

The value returned by main is the status code of the program: an int. If, 
however, your program uses the routine exit (or _exi t ) to terminate, the 
value returned by main is the argument passed to the call to exit (or to 
_exit). 

For example, if your program contains the call exit (l) the status is 1. 

Passing file information to child processes 

If your program uses the exec or spawn functions to create a new process, 
the new process will normally inherit all of the open file handles created by 
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the original process. However, some information about these handles will 
be lost, including the access mode used to open the file. For example, if 
your program opens a file for read-only access in binary mode, and then 
spawns a child process, the child process might corrupt the file by writing 
to it, or by reading from it in text mode. 

To allow child processes to inherit such information about open files, you 
must link your program with the object file FILEINFO.OBJ. For example: 

bcc test.c \borlandc\lib\fileinfo.obj 

The file information is passed in the environment variable _C_FILE_INFO. 
This variable contains encoded binary information, and your program 
should not attempt to read or modify its value. The child program must 
have been built with the C++ run-time library to inherit this information 
correctly. Other programs can ignore _C_FILE_INFO, and will not inherit 
file information. 



Pop-up screens 



POPUP.OBJ adds 

about 800 bytes of 

code to your 

program. 



When the run-time library encounters an unrecoverable error, or your 
program uses the assert macro with a false condition, the library displays an 
error message to the standard error file (normally the display screen) and 
terminates the program. However, if your program uses a windowing 
system such as Presentation Manager, or redirects standard error, these 
error messages might be invisible or overwrite existing screen displays. 
You can cause error messages to be displayed in a pop-up screen by 
including the object file POPUP.OBJ when you link your program. For 
example: bcc test.c \borlandclib\popup.obj 



Multi-thread programs 



See the online Help 

example for 

_beginthread 'to see 

how to use these 

functions and 

Jhreadidma 

program. 



OS/2 programs can create more than one thread of execution. OS/2 
provides a DosCreateThread function for this purpose. However, the C++ 
run-time library C2.LIB does not support more than one thread. If your 
program creates multiple threads, and these threads also use the C++ run- 
time library, you must use the C2MT.LIB library instead. 

The C2MT.LIB library provides the function Jbeginthread function, which 
you use to create threads. C2MT.LIB also provides the function _endthread, 
which terminates threads, and a global variable _threadid. This global 
variable points to a long integer that contains the current thread's 
identification number (also known as the thread ID). The header file 
stddef.h contains the declaration of threadid. 
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When you compile or link a program that uses multiple threads, you must 
use the -sm compiler switch. For example: 



bcc -sm thread. c 



Special care must be taken when using the signal function in a multi-thread 
program. See the description of the signal function for more information. 

See "The run-time libraries" section in Appendix A for information about 
linking to the DLL version of the run-time library. 
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Run-time functions 



Programming 

examples for each 

function are available 

in the online Help 

system. You can 

easily copy them from 

Help and paste them 

into your files. 



This chapter contains a detailed description of each function in the Borland 
C++ library. The functions are listed in alphabetical order, although a few 
of the routines are grouped by "family" (the exec. . . and spawn.. . functions, 
for example) because they perform similar or related tasks. 

Each function entry provides certain standard information. For instance, 
the entry for free 

■ Tells you which header file(s) contains the prototype for free. 

■ Summarizes what free does. 

■ Gives the syntax for calling free. 

■ Gives a detailed description of how free is implemented and how it 
relates to the other memory-allocation routines. 

■ Lists other language compilers that include similar functions. 

■ Refers you to related Borland C++ functions. 

The following sample library entry lists each entry section and describes 
the information it contains. The alphabetical listings start on page 10. 



Sample function entry 



header file name 



Function 
Syntax 



The function is followed by the header file(s) containing the prototype for 
function or definitions of constants, enumerated types, and so on used by 
function. 

Summary of what this function does. 

function (modifier parameter [, ...]); 

This gives you the declaration syntax for function; parameter names are 
italicized. The [,...] indicates that other parameters and their modifiers can 
follow. 

Portability is indicated by marks (■) in the columns of the portability table. 
A sample portability table is shown here: 
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Sample function entry 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ . 


OS/2 

















Each entry in the portability table is described in the following table. Any 
additional restrictions are discussed in the Remarks section. 



Remarks 
Return value 
See also 

Example 



DOS Available for DOS. 

UNIX Available under UNIX anctor POSIX. 

Win 1 6 Compatible with 1 6-bit Windows programs running on Microsoft Windows 3.1 , Windows 
for Workgroups 3.1 , and Windows for Workgroups 3.1 1 . 

Win 32 Available to 32-bit Windows programs running on Win32s 1 .0, and Windows NT 3.1 
applications. 



ANSI C Defined by the ANSI C Standard. 
ANSI C++ Included in the ANSI C++ proposal. 
OS/2 Available for OS/2. 



If more than one function is discussed and their portability features are 
identical, only one row is used. Otherwise, each function is represented in a 
separate row. 

This section describes what function does, the parameters it takes, and any 
details you need to use function and the related routines listed. 

The value that function returns (if any) is given here. If function sets any 
global variables, their values are also listed. 

Routines related to function that you might want to read about are listed 
here. If a routine name contains an ellipsis, it indicates that you should refer 
to a family of functions (for example, exec. . . refers to the entire family of 
exec functions: execl, execle, execlp, execlpe, execv, execve, execvp, and execvpe). 

The function examples have been moved into online Help so that you can 
easily cut-and-paste them to your own applications. 



abort 



stdlib.h 



Function 
Syntax 



Abnormally terminates a program. 

void abort (void) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 
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Remarks 

Return value 
See also 



abort 



abort causes an abnormal program termination by calling rafse(SIGABRT). If 
there is no signal handler for SIGABRT, then abort writes a termination 
message ("Abnormal program termination") on stderr, then aborts the 
program by a call to _exit with exit code 3. 

abort returns the exit code 3 to the parent process or to the operating system 
command processor. 

assert, atexit, _exit, exit, raise, signal, spawn. . . 




abs 



stdlib.h 



Function 
Syntax 

Remarks 



Return value 



See also 



Returns the absolute value of an integer. 



int abs(int x) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



abs returns the absolute value of the integer argument x. If abs is called 
when stdlib.h has been included, it's treated as a macro that expands to 
inline code. 

If you want to use the abs function instead of the macro, include #undef abs 
in your program, after the # include <stdlib.h>. 

This function can be used with bed and complex types. 

The abs function returns an integer in the range of to INT_MAX, with the 
exception that an argument with the value INTJVIIN is returned as 
INT_MIN. The values for INT_MAX and INT_MIN are defined in header 
file limits. h. 

bed, cabs, complex, fabs, labs 



access 



io.h 



Function 
Syntax 



Determines accessibility of a file. 

int access (const char *filename, int amode) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 






■ 
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access 



Remarks 



access checks the file named by filename to determine if it exists, and 
whether it can be read, written to, or executed. 

The list of amode values is as follows: 



Return value 



06 Check for read and write permission 

04 Check for read permission 

02 Check for write permission 

01 Execute (ignored) 

00 Check for existence of file 

Under DOS, OS/2, and Windows (16- and 32-bit) all existing files have read 
access {amode equals 04), so 00 and 04 give the same result. Similarly, amode 
values of 06 and 02 are equivalent because under OS/2 write access implies 
read access. 

If filename refers to a directory, access simply determines whether the 
directory exists. 

If the requested access is allowed, access returns 0; otherwise, it returns a 
value of -1, and the global variable errno is set to one of the following 
values: 



See also 



EACCES Permission denied 
ENOENT Path or file name not found 

chmod,fstat, stat 



acos, acosl 



math.h 



Function 
Syntax 



acos 
acosl 



Remarks 



Calculates the arc cosine. 

double acos (double x) ; 

long double acosl (long double x) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 


■ 




■ 


■ 






■ 



acos returns the arc cosine of the input value, acosl is the long double 
version; it takes a long double argument and returns a long double result. 
Arguments to acos and acosl must be in the range -1 to 1, or else acos and 
acosl return NAN and set the global variable errno to 

EDOM Domain error 
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Return value 



See also 



acos, acosl 



This function can be used with bed and complex types. 

acos and acosl of an argument between -1 and +1 return a value in the range 
to pi. Error handling for these routines can be modified through the 
functions jnatherr and jnatherrl. 

asin, atan, atanl, bed, complex, cos, jnatherr, sin, tan 




alloca 



malloc.h 



Function 
Syntax 



Remarks 



Allocates temporary stack space. 

void *alloca(size_t size); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


" 


■ 


■ 


■ 






■ 



alloca allocates size bytes on the stack; the allocated space is automatically 
freed up when the calling function exits. 

Because alloca modifies the stack pointer, do not place calls to alloca in an 
expression that is an argument to a function. 

The alloca function should not be used in the try-block of a C++ program. If 
an exception is thrown any values placed on the stack by alloca will be 
corrupted. 

If the calling function does not contain any references to local variables in 
the stack, the stack will not be restored correctly when the function exits, 
resulting in a program crash. To ensure that the stack is restored correctly, 
use the following code in the calling function: 

char *p; 

char dummy [ 5 ] ; 

dummy [0] = 0; 



Return value 
See also 



p = alloca (nbytes) ; 

If enough stack space is available, alloca returns a pointer to the allocated 
stack area. Otherwise, it returns NULL. 

malloc 



asctime 



time.h 



Function 



Converts date and time to ASCII. 
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asctime 



Syntax 



Remarks 



Return value 



See also 



char *asctime (const struct tm *tblock) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


" 


■ 


■ 


■ 


■ 



asctime converts a time stored as a structure in *tblock to a 26-character 
string of the same form as the ctime string: 

Sun Sep 16 01:03:52 1973\n\0 

asctime returns a pointer to the character string containing the date and 
time. This string is a static variable that is overwritten with each call to 

asctime. 

dime, difftime, ftime, gmtime, localtime, mktime, strftime, stime, time, tzset 



asin, asinl 



math.h 



Function 



Calculates the arc sine. 



Syntax 



Remarks 



asm 



asinl 



Return value 



See also 



double asin (double x) ; 

long double asinl (long double x) 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 


■ 




■ 


■ 






■ 



asin of a real argument returns the arc sine of the input value, asinl is the 
long double version; it takes a long double argument and returns a long 
double result. 

Real arguments to asin and asinl must be in the range -1 to 1, or else asin 
and asinl return NAN and set the global variable errno to 

EDOM Domain error 

This function can be used with bed and complex types. 

asin and asinl of a real argument return a value in the range -pi/2 to pi/2. 
Error handling for these functions can be modified through the functions 
jnatherr and jnatherrl. 

acos, atan, atanl, bed, complex, cos, jnatherr, sin, tan 
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assert 



assert 



assert.h 




Function 
Syntax 



Remarks 



Return value 
See also 



Tests a condition and possibly aborts. 

void assert (int test); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


" 



assert is a macro that expands to an if statement; if test evaluates to zero, 
assert prints a message on stderr and aborts the program (by calling abort). 

assert displays this message: 

Assertion failed: test, file filename, line linenum 

The filename and linenum listed in the message are the source file name and 
line number where the assert macro appears. 

If you place the #def ine NDEBUG directive ("no debugging") in the source 
code before the #include <assert .h> directive, the effect is to comment out 
the assert statement. 

None. 

abort 



atan, atanl 



math.h 



Function 
Syntax 



Remarks 



atan 
atanl 



Calculates the arc tangent. 

double atan (double x) ; 

long double atanl (long double x) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


- 


■ 


■ 


• 


■ 


■ 


■ 




■ 


■ 






■ 



atan calculates the arc tangent of the input value. 

atanl is the long double version; it takes a long double argument and 
returns a long double result. This function can be used with bed and complex 
types. 
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atan, atari I 



Return value 



See also 



atan and atanl of a real argument return a value in the range -pi/2 to pi/2. 
Error handling for these functions can be modified through the functions 
jnatherr and jnatherrl. 

acos, asin, atanl, bed, complex, cos, jnatherr, sin, tan 



atan2, atan2l 



math.h 



Function 
Syntax 



Remarks 



atan2 
atan2l 



Return value 



See also 



Calculates the arc tangent of y/x. 

double atan2 (double y, double x) ; 

long double atan21(long double y, long double x) 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


- 


■ 


■ 


■ 


■ 




■ 


■ 






■ 



atanl returns the arc tangent of y/x; it produces correct results even when 
the resulting angle is near pi/2 or -pi/2 (x near 0). If both x and y are set to 
0, the function sets the global variable errno to EDOM, indicating a domain 
error. 

atanll is the long double version; it takes long double arguments and 
returns a long double result. 

atanl and atanll return a value in the range -pi to pi. Error handling for 
these functions can be modified through the functions jnatherr and 
jnatherrl. 

acos, asin, atan, cos, jnatherr, sin, tan 



atexit 



stdlib.h 



Function 
Syntax 



Remarks 



Registers termination function. 

int atexit (void (JJSERENTRY * func) (void) ) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 


■ 


■ 


■ 



atexit registers the function pointed to by func as an exit function. Upon 
normal termination of the program, exit calls func just before returning to 
the operating system, func must be used with the JJSERENTRY calling 
convention. 
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Return value 
See also 



atexit 



Each call to atexit registers another exit function. Up to 32 functions can be 
registered. They are executed on a last-in, first-out basis (that is, the last 
function registered is the first to be executed). 

atexit returns on success and nonzero on failure (no space left to register 
the function). 

abort, _exit, exit, spawn.. . 




atof, _atold 



math.h 



Function 
Syntax 



atof 
atold 



Remarks 



Converts a string to a floating-point number. 

double atof (const char *s); 

long double _atold(const char *s); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


• 


■ 


■ 


■ 


■ 


■ 


■ 




■ 


■ 






■ 



Return value 



atof converts a string pointed to by s to double; this function recognizes the 
character representation of a floating-point number, made up of the 
following: 

a An optional string of tabs and spaces 

a An optional sign 

m A string of digits and an optional decimal point (the digits can be on both 

sides of the decimal point) 
q An optional e or E followed by an optional signed integer 

The characters must match this generic format: 

[whitespace] [sign] [ddd] [.] [ddd] [e I E[sign]ddd] 

atof also recognizes +INF and -INF for plus and minus infinity, and +NAN 
and -NAN for Not-a-Number. 

In this function, the first unrecognized character ends the conversion. 

_atold is the long double version; it converts the string pointed to by s to a 
long double. 

strtod and _strtold are similar to atof and _atold; they provide better error 
detection, and hence are preferred in some applications. 

atof and _atold return the converted value of the input string. 
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atof, atold 



See also 



If there is an overflow, atof (or _atold) returns plus or minus HUGE_VAL (or 
_LHUGE_VAL), errno is set to ERANGE (Result out of range), and jnatherr 
(or jnatherrl) is not called. 

atoi, atol, ecvt,fcvt, govt, scanf, strtod 



atoi 



stdlib.h 



Function 
Syntax 



Remarks 



Converts a string to an integer. 

int atoi (const char *s) ; 
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atoi converts a string pointed to by s to int; atoi recognizes (in the following 
order) 

■ An optional string of tabs and spaces 

■ An optional sign 

■ A string of digits 

The characters must match this generic format: 



Return value 
See also 



[zvs] [sn] [ddd] 

In this function, the first unrecognized character ends the conversion. There 
are no provisions for overflow in atoi (results are undefined). 

atoi returns the converted value of the input string. If the string cannot be 
converted to a number of the corresponding type (int), atoi returns 0. 

atof, atol, ecvt,fcvt, govt, scanf, strtod 



atol 



stdlib.h 



Function 
Syntax 



Remarks 



Converts a string to a long. 

long atol(const char *s); 
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atol converts the string pointed to by s to long, atol recognizes (in the 
following order) 
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Return value 
See also 



atol 



■ An optional string of tabs and spaces 
n An optional sign 

■ A string of digits 

The characters must match this generic format: 

[ws] [sn] [ddd] 

In this function, the first unrecognized character ends the conversion. There 
are no provisions for overflow in atol (results are undefined). 

atol returns the converted value of the input string. If the string cannot be 
converted to a number of the corresponding type (long), atol returns 0. 

atof, atoi, ecvt,fcvt, gcvt, scanf, strtod, strtol, strtoul 




atold 



See atof. 



_beginthread 



process.h 



Function 
Syntax 



Remarks 



Starts execution of a new thread. 

int _beginthread(void (*start_address) (void *), unsigned stack_size, void *arglist) 
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The Jbeginthread function creates and starts a new thread. The thread starts 
execution at start jiddr ess. The size of its stack in bytes is stack_size; the stack 
is allocated by the operating system after the stack size is rounded up to the 
next multiple of 4096. The thread is passed arglist as its only parameter; it 
can be NULL, but must be present. The thread terminates by simply 
returning, or by calling _endthread. 

This function must be used instead of the operating system thread-creation 
API function because Jbeginthread performs initialization required for 
correct operation of the run-time library functions. 

This function is available in C2MT.LIB, the multithread library; it is not in 
C2.LIB, the single-thread library. 
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_beginthread 



Return value Jbeginthread returns the thread ID of the new thread. In the event of an 

error, the function returns -1, and the global variable errno is set to one of 
the following values: 



EAGAIN 
EINVAL 



Too many threads 
Invalid request 



See also 



endthread 



bsearch 



stdlib.h 



Function 
Syntax 



Remarks 



Binary search of an array. 

void *bsearch (const void *key, const void *base, size_t nelem, size_t width, 
int (JJSERENTRY *fcmp) (const void *, const void *)); 
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bsearch searches a table (array) of nelem elements in memory, and returns 
the address of the first entry in the table that matches the search key. The 
array must be in order. If no match is found, bsearch returns 0. Note that 
because this is a binary search, the first matching entry is not necessarily 
the first entry in the table. 

The type size J is defined in stddef.h header file. 

■ nelem gives the number of elements in the table. 

■ width specifies the number of bytes in each table entry. 

The comparison routine fcmp must be used with the _USERENTRY calling 
convention. 

fcmp is called with two arguments: eleml and eleml. Each argument points 
to an item to be compared. The comparison function compares each of the 
pointed-to items (*eleml and *elem2), and returns an integer based on the 
results of the comparison. 

For bsearch, the fcmp return value is 

■ < if *eleml < *elem2 

■ == if *eleml -= *elem2 

■ > if *eleml > *elem2 
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bsearch 



Return value 



See also 



bsearch returns the address of the first entry in the table that matches the 
search key. If no match is found, bsearch returns 0. 

Ifind, Isearch, qsort 




cabs, cabsl 



math.h 



Function 
Syntax 



Remarks 



cabs 
cabsl 



Calculates the absolute value of complex number. 

double cabs (struct complex z); 

long double cabsl (struct _complexl z); 
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cabs is a macro that calculates the absolute value of z, a complex number, z 
is a structure with type complex. The structure is defined in math.h as 

struct complex { 
double x, y; 
}; 



Return value 



struct _complexl { 

long double x, y; 
}; 

where x is the real part, and y is the imaginary part. 

Calling cabs is equivalent to calling sort with the real and imaginary 
components of z, as shown here: 

sqrt(z.x * z.x + z.y * z.y) 

cabsl is the long double version; it takes a structure with type _complexl as 
an argument, and returns a long double result. 

If you're using C++, you may also use the complex class defined in 
complex.h, and use the function abs to get the absolute value of a complex 
number. 

cabs (or cabsl) returns the absolute value of z, a double. On overflow, cabs (or 
cabsl) returns HUGE_VAL (or _LHUGE_VAL) and sets the global variable 
errno to 

ERANGE Result out of range 
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cabs, cabsl 



See also 



Error handling for these functions can be modified through the functions 
jnatherr and jnatherrl. 

abs, complex, errno (global variable), fobs, labs, jnatherr 



calloc 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Allocates main memory. 

void *calloc(size_t nitems, size_t size);. 
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calloc provides access to the C memory heap. The heap is available for 
dynamic allocation of variable-sized blocks of memory. Many data 
structures, such as trees and lists, naturally employ heap memory 
allocation. 

calloc allocates a block of size nitems x size. The block is cleared to 0. 

calloc returns a pointer to the newly allocated block. If not enough space 
exists for the new block or if nitems or size is 0, calloc returns NULL. 

free, malloc, realloc 



ceil, ceill 



math.h 



Function 
Syntax 



Remarks 



Return value 



See also 



ceil 
ceill 



Rounds up. 

double ceil (double x) ; 

long double ceill (long double x) 
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ceil finds the smallest integer not less than x. ceill is the long double version; 
it takes a long double argument and returns a long double result. 

These functions return the integer found as a double (ceil) or a long double 

(ceill). 

floor, finod 
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c exit 



_c_exit 

Function 
Syntax 



Remarks 

Return value 
See also 



process.h 



Performs _exit cleanup without terminating the program. 

void _c_exit (void) ; 
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_c_exit performs the same cleanup as _exit, except that it does not terminate 
the calling process. 

None. 

abort, atexit, _cexit, exec. . ., _exit, exit, signal, spawn.. . 



cexit 



process.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Performs exit cleanup without terminating the program. 

void _cexit(void) ; 
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_cexit performs the same cleanup as exit, except that it does not close files or 
terminate the calling process. Buffered output (waiting to be output) is 
written, and any registered "exit functions" (posted with atexit) are called. 

None. 

abort, atexit, _c_exit, exec. .., _exit, exit, signal, spawn.. . 



cgets 



conio.h 



Function 
Syntax 



Remarks 



Reads a string from the console. 

char *cgets(char *str) ; 
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cgets reads a string of characters from the console, storing the string (and 
the string length) in the location pointed to by str. 
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cgets 



Return value 
See also 



cgets reads characters until it encounters a carriage-return/linefeed 
(CR/LF) combination, or until the maximum allowable number of char- 
acters have been read. If cgets reads a CR/LF combination, it replaces the 
combination with a \0 (null character) before storing the string. 

Before cgets is called, set str[0] to the maximum length of the string to be 
read. On return, str[l] is set to the number of characters actually read. The 
characters read start at str[2] and end with a null character. Thus, str must 
be at least str[0] plus 2 bytes long. 

This function should not be used in PM applications. 

On success, cgets returns a pointer to str[2], 

cputs,fgets, getch, getche, gets 



chdir 



dir.h 



Function 
Syntax 



Remarks 



Return value 



Changes current directory. 

int chdir(const char *path) ; 
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chdir causes the directory specified by path to become the current working 
directory, path must specify an existing directory. 

A drive can also be specified in the path argument, such as 

chdir("a:\\BC") 

but this changes only the current directory on that drive; it doesn't change 
the active drive. 

Only the current process is affected. 

Upon successful completion, chdir returns a value of 0. Otherwise, it returns 
a value of -1, and the global variable errno is set to 



See also 



ENOENT Path or file name not found 

getcurdir, getcwd, getdisk, mkdir, rrndir, setdisk, system 



chdrive 



direct.h 



Function 



Sets current disk drive. 
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chdrive 



Syntax 

Remarks 

Return value 
See also 



int _chdrive(int drive); 
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_chdrive sets the current drive to the one associated with drive: 1 for A, 
2 for B, 3 for C, and so on. 

Only the current process is affected. 

_chdrive returns if the current drive was changed successfully; otherwise, 
it returns -1. 

dos setdrive 



chmod 



dos.h, io.h 



chmod 



Obsolete function. See rtl chmod. 



sys\stat.h 



Function 
Syntax 



Remarks 



Changes file access mode. 

int chmod(const char *path, int amode) ; 
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chmod sets the file-access permissions of the file given by path according to 
the mask given by amode. path points to a string. 

amode can contain one or both of the symbolic constants S_IWRITE and 
SJREAD (defined in sys\stat.h). 



Value of amode 



Access permission 



SJWRITE 

SJREAD 

S_IREAD|S_IWRITE 



Permission to write 
Permission to read 
Permission to read and write 



Write permission implies read permission. 

This function will fail (EACCES) if the file is currently open in any process. 
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chmod 



Return value Upon successfully changing the file access mode, chmod returns 0. Other- 

wise, chmod returns a value of -1. 

In the event of an error, the global variable errno is set to one of the 
following values: 



See also 



EACCES Permission denied 
ENOENT Path or file name not found 

access, _rtl_chmod,fstat, open, sopen, stat 



chsize 



io.h 



Function 
Syntax 



Remarks 



Return value 



Changes the file size. 

int chsize(int handle, long size); 
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chsize changes the size of the file associated with handle. It can truncate or 
extend the file, depending on the value of size compared to the file's original 
size. 

The mode in which you open the file must allow writing. 

If chsize extends the file, it will append null characters (\0). If it truncates 
the file, all data beyond the new end-of-file indicator is lost. 

On success, chsize returns 0. On failure, it returns -1 and the global variable 
errno is set to one of the following values: 



See also 



EACCES Permission denied 
EBADF Bad file number 

ENOSPC No space left on device 

close,creat, open, truncate, _rtl_creat 



clear87 



float.h 



Function 
Syntax 



Clears floating-point status word. 

unsigned int _clear87 (void) ; 
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clear87 



Remarks 



Return value 



See also 
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_clear87 clears the floating-point status word, which is a combination of the 
80x87 status word and other conditions detected by the 80x87 exception 
handler. 

The bits in the value returned indicate the floating-point status before it 
was cleared. For information on the status word, refer to the constants 
defined in float.h. 

_control87, Jpreset, _status87 




clearerr 



stdio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Resets error indication. 

void clearerr (FILE *stream) ; 
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clearerr resets the named stream's error and end-of-file indicators to 0. Once 
the error indicator is set, stream operations continue to return error status 
until a call is made to clearerr or rewind. The end-of-file indicator is reset 
with each input operation. 

None. 

eof,feof,f error, perror, rewind 



clock 



time.h 



Function 
Syntax 



Remarks 



Determines processor time. 

clock_t clock (void) ; 
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clock can be used to determine the time interval between two events. To 
determine the time in seconds, the value returned by clock should be 
divided by the value of the macro CLK_TCK. 
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clock 



Return value 



See also 



The clock function returns the processor time elapsed since the beginning of 
the program invocation. If the processor time is not available, or its value 
cannot be represented, the function returns the value -1. 



time 



close 



io.h 



Obsolete function. See rtl close. 



close 



io.h 



Function 
Syntax 



Remarks 



Return value 



Closes a file. 

int close(int handle); 
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close closes the file associated with handle, a file handle obtained from a 
_rtl_creat, creat, creatnew, creattemp, dup, dup2, _rtl_open, or open call. 

The function does not write a Ctrl-Z character at the end of the file. If you 
want to terminate the file with a Ctrl-Z, you must explicitly output one. 

Upon successful completion, close returns 0. Otherwise, the function returns 
a value of -1. 

close fais if handle is not the handle of a valid, open file, and the global 
variable errno is set to 



See also 



EBADF Bad file number 

chsize, creat, creatnew, dup,fclose, open, _rtl_close, sopen 



closedir 



dirent.h 



Function 
Syntax 



Closes a directory stream. 

int closedir (DIR *dirp) ; 
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closedir 



Remarks 



Return value 



See also 
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On UNIX platforms, closedir is available on POSIX-compliant systems. 

The closedir function closes the directory stream dirp, which must have been 
opened by a previous call to opendir. After the stream is closed, dirp no 
longer points to a valid directory stream. 

If closedir is successful, it returns 0. Otherwise, closedir returns -1 and sets 
the global variable errno to 

EBADF The dirp argument does not point to a valid open directory 

stream 

errno (global variable), opendir, readdir, rewinddir 




clreol 



conio.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Clears to end of line in text window. 

void clreol (void) ; 
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clreol clears all characters from the cursor position to the end of the line 
within the current text window, without moving the cursor. 

This function should not be used in PM applications. 

None. 

clrscr, delline, window 



clrscr 



conio.h 



Function 
Syntax 



Clears the text-mode window. 

void clrscr (void) ; 
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clrscr 



Remarks clrscr clears the current text window and places the cursor in the upper 

left-hand corner (at position 1,1). 

b^ This function should not be used in PM applications. 

Return value None. 

See also clreol, delline, window 



control87 



float.h 



Function 
Syntax 



Remarks 



Manipulates the floating-point control word. 

unsigned int _contro!87 (unsigned int newcw, unsigned int mask) 
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_control87 retrieves or changes the floating-point control word. 

The floating-point control word is an unsigned int that, bit by bit, specifies 
certain modes in the floating-point package; namely, the precision, infinity, 
and rounding modes. Changing these modes lets you mask or unmask 
floating-point exceptions. 

_control87 matches the bits in mask to the bits in newcw. If a mask bit equals 
1, the corresponding bit in newcw contains the new value for the same bit in 
the floating-point control word, and _control87 sets that bit in the control 
word to the new value. 

Here's a simple illustration: 



Return value 



See also 



Original control wore 


I: 0100 


0011 


0110 


0011 


mask: 


1000 


0001 


0100 


1111 


newcw: 


1110 


1001 


0000 


0101 


Changing bits: 


lxxx 


xxxl 


xOxx 


0101 



If mask equals 0, _control87 returns the floating-point control word without 
altering it. 

The bits in the value returned reflect the new floating-point control word. 
For a complete definition of the bits returned by _control87, see the header 
file float.h. 

_clear87, Jpreset, signal, _status87 
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cos, cosl 



COS, cosl 



Function 



Syntax 



Remarks 



cos 



cosl 



Return value 



See also 



math.h 



Calculates the cosine of a value. 



double cos (double x) ; 

long double cosl (long double x) 
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cos computes the cosine of the input value. The angle is specified in radians. 

cosl is the long double version; it takes a long double argument and returns 
a long double result. 

This function can be used with bed and complex types. 

cos of a real argument returns a value in the range -1 to 1. Error handling 
for these functions can be modified through jnatherr (or jmaiherrl). 

acos, asin, atari, atanl, bed, complex, jnatherr, sin, tan 



cosh, coshl 



math.h 



Function 



Syntax 



cosh 
coshl 



Remarks 



Return value 



Calculates the hyperbolic cosine of a value. 

double cosh(double x) ; 

long double coshl (long double x) ; 
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cosh computes the hyperbolic cosine, (e x + e" x )/2. coshl is the long double 
version; it takes a long double argument and returns a long double result. 

This function can be used with bed and complex types. 

cosh returns the hyperbolic cosine of the argument. 

When the correct value would create an overflow, these functions return 
the value HUGE_VAL (cosh) or _LHUGE_VAL (coshl) with the appropriate 
sign, and the global variable errno is set to ERANGE. Error handling for 
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cosh, coshl 



See also 



these functions can be modified through the functions jnatherr and 
jnatherrl. 

acos, asin, atari, atanl, bed, complex, cos, jnatherr, sin, sink, tan, tank 



country 



dos.h 



Function 
Syntax 



Remarks 



The country function 

is not affected by 

setlocale. 



Returns country-dependent information. 

struct COUNTRY *country(int xcode, struct COUNTRY *cp) ; 
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country specifies how certain country-dependent data (such as dates, times, 
and currency) will be formatted. The values set by this function depend on 
the operating system version being used. 

The COUNTRY structure pointed to by cp is filled with the country- 
dependent information of the current country (if xcode is set to zero), or the 
country given by xcode. 

The structure COUNTRY is defined as follows: 



struct COUNTRY { 

int co_date; 

char co_curr [5] ; 

char co_thsep[2] 

char co_desep[2] 

char co_dtsep[2] 

char co_tmsep[2] 

char co_currstyle; 

char co_digits; 

char co_time; 

long co_case; 

char co_dasep[2] ; 

char co_fill[10]; 
}; 

The date format in co date is 



■ for the U.S. style of month, day, year. 

■ 1 for the European style of day, month, year. 

■ 2 for the Japanese style of year, month, day. 

Currency display style is given by cojeurrstyle as follows: 



/* date format */ 

/* currency symbol */ 

/* thousands separator */ 

/* decimal separator */ 

/* date separator */ 

/* time separator */ 

/* currency style */ 

/* significant digits in currency */ 

/* time format */ 

/* NOT USED ON OS/2 */ 

/* data separator */ 

/* filler */ 
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country 



Return value 



a for the currency symbol to precede the value with no spaces between 
the symbol and the number. 

a 1 for the currency symbol to follow the value with no spaces between the 
number and the symbol. 

d 2 for the currency symbol to precede the value with a space after the 
symbol. 

a 3 for the currency symbol to follow the number with a space before the 
symbol. 

On success, country returns the pointer argument cp. On error, it returns 
NULL. 




cprintf 



conio.h 



Function 
Syntax 



Remarks 



Writes formatted output to the screen. 

int cprintf (const char * format [, argument, 
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cprintf accepts a series of arguments, applies to each a format specifier 
contained in the format string pointed to by format, and outputs the 
See printf for details formatted data directly to the current text window on the screen. There 
on format specifiers. mus t be the same number of format specifiers as arguments.. 

Unlike fprin if and printf cprintf does not translate linefeed characters (\n) 
into carriage-return/linefeed character pairs (\r\n). Tab characters 
(specified by \t) are not expanded into spaces. 



Return value 
See also 



This function should not be used in PM applications. 
cprintf returns the number of characters output. 

fprintf printf putch, sprintf vprintf 



cputs 



conio.h 



Function 
Syntax 



Writes a string to the screen. 

int cputs (const char *str) ; 
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cputs 



Remarks 



Return value 
See also 



cputs writes the null-terminated string str to the current text window. It 
does not append a newline character. 

Unlike puts, cputs does not translate linefeed characters (\n) into carriage- 
return/linefeed character pairs (\r\n). 

This function should not be used in PM applications. 

cputs returns the last character printed. 

cgets,fputs, putch, puts 



creat 



io.h 



Obsolete function. See rtl creat. 



creat 



io.h 



Function 
Syntax 



Remarks 



Creates a new file or overwrites an existing one. 

int creat (const char *path, int amode) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/ 


■ 


■ 


■ 


■ 






■ 



creat creates a new file or prepares to rewrite an existing file given by path, 
amode applies only to newly created files. 

A file created with creat is always created in the translation mode specified 
by the global variable Jmode (O.TEXT or 0_BINARY). 

If the file exists and the write attribute is set, creat truncates the file to a 
length of bytes, leaving the file attributes unchanged. If the existing file 
has the read-only attribute set, the creat call fails and the file remains 
unchanged. 

The creat call examines only the S_IWRITE bit of the access-mode word 
amode. If that bit is 1, the file can be written to. If the bit is 0, the file is 
marked as read-only. All other operating system attributes are set to 0. 

amode can be one of the following (defined in sys\stat.h): 
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creat 



Return value 



Value of amode 



SJWRITE 

SJREAD 

S_IREAD|S_IWRITE 



Access permission 



Permission to write 
Permission to read 
Permission to read and write 




Write permission implies read permission. 

Upon successful completion, creat returns the new file handle, a non- 
negative integer; otherwise, it returns -1. 

In the event of error, the global variable errno is set to one of the following: 



See also 



EACCES Permission denied 
EMFILE Too many open files 
ENOENT Path or file name not found 

chmod, chsize, close, creatnew, creattemp, dup, dup2, Jmode (global variable), 
fopen, open, _rtl_creat, sopen, write 



creatnew 



io.h 



Function 
Syntax 



Remarks 



Return value 



Creates a new file. 

int creatnew (const char *path, int mode); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



creatnew is identical to _rtl_creat with one exception: If the file exists, 
creatnew returns an error and leaves the file untouched. 

The mode argument to creatnew can be zero or an OR-combination of any 
one of the following constants (defined in dos.h): 

FA_HIDDEN Hidden file 
FA_RDONLY Read-only attribute 
FA_SYSTEM System file 

Upon successful completion, creatnew returns the new file handle, a non- 
negative integer; otherwise, it returns -1. 

In the event of error, the global variable errno is set to one of the following 
values: 



EACCES 
EEXIST 



Permission denied 
File already exists 
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creatnew 



See also 



EMFILE Too many open files 

ENOENT Path or file name not found 

close, _rtl_creat, creat, creattemp, _dos_creatnew, dup, Jmode (global variable), 
open 



creattemp 



io.h 



Function 
Syntax 



Remarks 



Remember that a 

backslash in path 

requires 'W. 



Return value 



Creates a unique file in the directory associated with the path name. 

int creattemp (char *path, int attrib) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



A file created with creattemp is always created in the translation mode 
specified by the global variable Jmode (0_TEXT or O.BINARY). 

path is a path name ending with a backslash (\). A unique file name is 
selected in the directory given by path. The newly created file name is 
stored in the path string supplied, path should be long enough to hold the 
resulting file name. The file is not automatically deleted when the program 
terminates. 

creattemp accepts attrib, an OS/2 attribute word. Upon successful file 
creation, the file pointer is set to the beginning of the file. The file is opened 
for both reading and writing. 

The attrib argument to creattemp can be zero or an OR-combination of any 
one of the following constants (defined in dos.h): 

FA_HIDDEN Hidden file 
FA_RDONLY Read-only attribute 
FA_SYSTEM System file 

Upon successful completion, the new file handle, a nonnegative integer, is 
returned; otherwise, -1 is returned. 

In the event of error, the global variable errno is set to one of the following 
values: 



See also 



EACCES Permission denied 

EMFILE Too many open files 

ENOENT Path or file name not found 

close, _rtl_creat, creat, creatnew, dup, Jmode (global variable), open 
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_crotl, _crotr 



crotl, crotr 



Function 
Syntax 



Remarks 



Return value 



See also 



stdlib.h 



Rotates an unsigned char left or right. 

unsigned char _crotl (unsigned char val, int count); 
unsigned char _crotr (unsigned char val, int count); 




DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




" 


■ 






■ 



_crotl rotates the given val to the left count bits. _crotr rotates the given val to 
the right count bits. 

The argument val is an unsigned char, or its equivalent in decimal or hexa- 
decimal form. 

The functions return the rotated val. 

■ _crotl returns the value of val left-rotated count bits. 

■ _crotr returns the value of val right-rotated count bits. 

Jrotl, Jrotr, jroil, _rotr 



cscanf 



conio.h 



Function 
Syntax 



Remarks 



See scant for details 
on format specifiers. 



Scans and formats input from the console. 

int cscanf (char * format [, address, ...]); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 






■ 






■ 



cscanf scans a series of input fields one character at a time, reading directly 
from the console. Then each field is formatted according to a format 
specifier passed to cscanf in the format string pointed to by format. Finally, 
cscanf stores the formatted input at an address passed to it as an argument 
following format, and echoes the input directly to the screen. There must be 
the same number of format specifiers and addresses as there are input 
fields. 

cscanf might stop scanning a particular field before it reaches the normal 
end-of -field (whitespace) character, or it might terminate entirely for a 
number of reasons. See scanf for a discussion of possible causes. 

This function should not be used in PM applications. 
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cscanf 



Return value 



See also 



cscanf returns the number of input fields successfully scanned, converted, 
and stored; the return value does not include scanned fields that were not 
stored. If no fields were stored, the return value is 0. 

If cscanf attempts to read at end-of-file , the return value is EOF. 

fscanf getche, scanf sscanf 



ctime 



time.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Converts date and time to a string. 

char *ctime (const time_t *time) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



ctime converts a time value pointed to by time (the value returned by the 
function time) into a 26-character string in the following form, terminating 
with a newline character and a null character: 

Mon Nov 21 11:31:54 1983\n\0 

All the fields have constant width. 

The global long variable Jimezone contains the difference in seconds 
between GMT and local standard time (in PST, Jimezone is 8x60x60). The 
global variable _daylight is nonzero if and only if the standard U.S. daylight 
saving time conversion should be applied. These variables are set by the 
tzset function, not by the user program directly. 

ctime returns a pointer to the character string containing the date and time. 
The return value points to static data that is overwritten with each call to 
ctime. 

asctime, _daylight (global variable), diff time, f time, getdate, gmtime, localtime, 
settime, time, Jimezone (global variable), tzset 



cwait 



process.h 



Function 
Syntax 



Waits for child process to terminate. 

int cwait (int *statloc, int pid, int action); 
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cwait 



Remarks 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 








■ 






■ 



The cwait function waits for a child process to terminate. The process ID of 
the child to wait for is pid. If statloc is not NULL, it points to the location 
where cwait will store the termination status. The action specifies whether to 
wait for the process alone, or for the process and all of its children. 

If the child process terminated normally (by calling exit, or returning from 
main), the termination status word is defined as follows: 




Bits 0-7 Zero. 

Bits 8-1 5 The least significant byte of the return code from the child 

process. This is the value that is passed to exit, or is returned 
from main. It the child process simply exited from main with- 
out returning a value, this value will be unpredictable. 

If the child process terminated abnormally, the termination status word is 
defined as follows: 

Bits 0-7 Termination information about the child: 



1 
2 
3 

Bits 8-15 Zero. 



Critical error abort. 

Execution fault, protection exception. 

External termination signal. 



Return value 



If pid is 0, cwait waits for any child process to terminate. Otherwise, pid 
specifies the process ID of the process to wait for; this value must have been 
obtained by an earlier call to an asynchronous spawn function. 

The acceptable values for action are WAIT_CHILD, which waits for the 
specified child only, and WAIT_GRANDCHILD, which waits for the 
specified child and all of its children. These two values are defined in 
process.h. y 

When cwait returns after a normal child process termination, it returns the 
process ID of the child. 

When cwait returns after an abnormal child termination, it returns -1 to the 
parent and sets errno to EINTR (the child process terminated abnormally). 

If cwait returns without a child process completion, it returns a -1 value 
and sets errno to one of the following values: 
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cwait 



See also 



ECHILD 
EINVAL 

spawn, wait 



No child exists or the pid value is bad 
A bad action value was specified 



delline 



conio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Deletes line in text window. 

void delline (void) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



delline deletes the line containing the cursor and moves all lines below it 
one line up. delline operates within the currently active text window. 

This function should not be used in PM applications. 

None. 

clreol, clrscr, insline, window 



difftime 



time.h 



Function 
Syntax 



Remarks 
Return value 
See also 



Computes the difference between two times. 

double difftime (time_t time2,' time_t timel); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


i 


■ 


■ 


■ 


■ 


■ 



difftime calculates the elapsed time in seconds, from timel to timel. 

difftime returns the result of its calculation as a double. 

asctime, ctime, _daylight (global variable), gmtime, localtime, time, Jimezone 
(global variable) 



div 



stdlib.h 



Function 
Syntax 



Divides two integers, returning quotient and remainder. 

div_t div(int numer, int denom) ; 
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div 



Remarks 



Return value 
See also 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 


■ 


■ 


■ 



div divides two integers and returns both the quotient and the remainder as 
a div J. type, numer and denom are the numerator and denominator, 
respectively. The div J, type is a structure of integers defined (with typedef) 
in stdlib.h as follows: 

typedef struct { 

int quot; /* quotient */ 

int rem; /* remainder */ 
} div_t; 

div returns a structure whose elements are quot (the quotient) and rem (the 
remainder). 

Idiv 




dos close 



dos.h 



Function 
Syntax 



Remarks 
Return value 

See also 



Closes a file. 

unsigned _dos_close(int handle); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


" 




■ 








■ 



_dos_close closes the file associated with handle, handle is a file handle 
obtained from a _dos_creat, _dos_creatnew, or _dos_open call. 

Upon successful completion, _dos_close returns 0. Otherwise, it returns the 
operating system error code and the global variable errno is set to 

EBADF Bad file number 

_dos_creat, _dos_open, _dos_read, _dos_write 



dos creat 



dos.h, io.h 



Function 
Syntax 



Creates a new file or overwrites an existing one. 

unsigned _dos_creat (const char *path,int attrib,int *handlep); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 








" 
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dos creat 



Remarks 



_dos_creat opens the file specified by path. The file is always opened in 
binary mode. Upon successful file creation, the file pointer is set to the 
beginning of the file. _dos_creat stores the file handle in the location pointed 
to by handlep. The file is opened for both reading and writing. 

If the file already exists, its size is reset to 0. (This is essentially the same as 
deleting the file and creating a new file with the same name.) 



Return value 



See also 



FA_RDONLY Read-only attribute 
FAJHIDDEN Hidden file 
FA_SYSTEM System file 

The attrib argument is an ORed combination of one or more of the 
following constants (defined in dos.h): 

_A_NORMAL Normal file 

_A_RDONLY Read-only file 

_A_HIDDEN Hidden file 

_A_SYSTEM System file 

Upon successful completion, _dos_creat returns 0. If an error occurs, 
_dos_creat returns the operating system error code. 

In the event of error, the global variable errno is set to one of the following 
values: 

EACCES Permission denied 
EMFILE Too many open files 

ENOENT Path or file name not found 

chsize, close, creat, creatnew, creattemp, _rtl_chmod, _rtl_close 



dos creatnew 



dos.h 



Function 
Syntax 



Remarks 



Creates a new file. 

unsigned _dos_creatnew( const char *path, int attrib, int *handlep) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 








■ 



_dos_creatnezv creates and opens the new file path. The file is given the 
access permission attrib, an operating-system attribute word. The file is 
always opened in binary mode. Upon successful file creation, the file 
handle is stored in the location pointed to by handlep, and the file pointer is 
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dos creatnew 



Return value 



See also 



set to the beginning of the file. The file is opened for both reading and 
writing. 

If the file already exists, _dos_creatnew returns an error and leaves the file 
untouched. 

The attrib argument to _dos_creatnew is an OR combination of one or more 
of the following constants (defined in dos.h): 

_A_NORMAL Normal file 

_A_RDONLY Read-only file 

_A_HIDDEN Hidden file 

_A_SYSTEM System file 

Upon successful completion, _dos_creatnew returns 0. Otherwise, it returns 
the operating system error code, and the global variable errno is set to one 
of the following: 

EACCES Permission denied 

EEXIST File already exists 

EMFILE Too many open files 

ENOENT Path or file name not found 

creatnew, _dos_close, _dos_creat, _dos_getfileattr, _dos_setfileattr 




dos findfirst 



dos.h 



Function 
Syntax 



Searches a disk directory. 

unsigned _dos_findfirst (const char *pathname, int attrib, 
struct find_t *ffblk); 



Remarks 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




" 








■ 



_dos_findfirst begins a search of a disk directory. 

pathname is a string with an optional drive specifier, path, and file name of 
the file to be found. The file name portion can contain wildcard match 
characters (such as ? or *). If a matching file is found, the find_t structure 
pointed to by jfblk is filled with the file-directory information. 

attrib is an operating system file-attribute word used in selecting eligible 
files for the search, attrib is an OR combination of one or more of the 
following constants (defined in dos.h): 
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dos findfirst 



_A_NORMAL 
_A_RDONLY 
_A_HIDDEN 
_A_SYSTEM 
_A_VOLID 
_A_SUBDIR 
A ARCH 



Normal file 
Read-only attribute 
Hidden file 
System file 
Volume label 
Directory 
Archive 



For more detailed information about these attributes, refer to your 
operating system reference manuals. 

Note that wrjime and wr_date contain bit fields for referring to the file's 
date and time. The structure of these fields was established by the operat- 
ing system. 



Return value 



wr time: 


Bits 0-4 


Bits 5-10 


Bits 11-15 


wr date: 


Bits 0-4 


Bits 5-8 


Bits 9-15 



See also 



The result of seconds divided by 2 (for example, 10 

here means 20 seconds) 

Minutes 

Hours 

Day 

Month 

Years since 1980 (for example, 9 here means 1989) 

_dos_findfirst returns on successfully finding a file matching the search 
pathname. When no more files can be found, or if there is some error in the 
file name, the operating system error code is returned, and the global 
variable errno is set to 

ENOENT Path or file name not found 

_dosJindnext 



dos findnext 



dos.h 



Function 
Syntax 



Remarks 



Continues _dos_findfirst search. 

unsigned _dos_f indnext ( struct find_t *ffblk) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 








■ 



_dos_findnext is used to fetch subsequent files that match the pathname given 
in _dos_findfirst. ffblk is the same block filled in by the _dos_findfirst call. This 
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dos findnext 



Return value 



See also 



block contains necessary information for continuing the search. One file 
name for each call to _dos_findnext is returned until no more files are found 
in the directory matching the pathname. 

_dos_findnext returns on successfully finding a file matching the search 
pathname. When no more files can be found, or if there is some error in the 
file name, the operating system error code is returned, and the global 
variable errno is set to 

ENOENT Path or file name not found 

_dosJindfirst 




_dos_getdate, _dos_setdate, getdate, setdate 



dos.h 



Function 
Syntax 



Gets and sets system date. 

void _dos_getdate( struct dosdate_t *datep) ; 
unsigned _dos_setdate( struct dosdate_t *datep) 
void getdate (struct date *datep) ; 
void setdate (struct date *datep) ; 



Remarks 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 








■ 



getdate fills in the date structure (pointed to by datep) with the system's 
current date, setdate sets the system date (month, day, and year) to that in 
the date structure pointed to by datep. 

The date structure is defined as follows: 



struct date { 
int da_year; 
char da_day; 
char da_mon; 

}; 



/* current year */ 

/* day of the month */ 

/* month (1 = Jan) */ 



_dos_getdate fills in the dosdatej structure (pointed to by datep) with the 
system's current date. 

The dosdate t structure is defined as follows: 



struct dosdate_t { 




unsigned char day; 


/* 1-31 */ 


unsigned char month; 


/* 1-12 */ 


unsigned int year; 


/* 1980 - 2099 */ 


unsigned char dayofweek; 


/* - 6 (0=Sunday) */ 
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_dos_getdate, _dos_setdate, getdate, setdate 



Return value 



See also 



_dos_getdate, getdate, and setdate do not return a value. 

If the date is set successfully, _dos_setdate returns 0. Otherwise, it returns a 
nonzero value and the global variable errno is set to 

EINVAL Invalid date 

ctime, gettime, settime 



_dos_getdiskfree 



dos.h 



Function 
Syntax 



Remarks 



Gets disk free space. 

unsigned _dos_getdiskfree (unsigned char drive, struct diskfree_t *dtable) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


' 




■ 








■ 



_dos_getdiskfree accepts a drive specifier in drive (0 for default, 1 for A, 2 for 
B, and so on) and fills in the diskfreej structure pointed to by dtable with 
disk characteristics. 

The diskfreej structure is defined as follows: 

struct diskfreej: { 

unsigned avail_clusters; /* available clusters */ 

unsigned total_clusters; /* total clusters */ 

unsigned bytes_per_sector; /* bytes per sector */ 

unsigned sectors_per_cluster; /* sectors per cluster */ 



Return value _dos_getdiskfree returns if successful. Otherwise, it returns a nonzero value 

and the global variable errno is set to 

EINVAL Invalid drive specified 



_dos_getdrive, _dos_setdrive 



dos.h 



Function 
Syntax 



Gets and sets the current drive number. 

void _dos_getdrive (unsigned *drivep) ; 

void _dos_setdrive (unsigned drivep, unsigned *ndrives); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 








■ 
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_dos_getdrive, _dos_setdrive 



Remarks 



Return value 
See also 



_dos_getdrive gets the current drive number. 

_dos_setdrive sets the current drive and stores the total number of drives at 
the location pointed to by ndrives. 

The drive numbers at the location pointed to by drivep are as follows: 1 for 
A, 2 for B, 3 for C, and so on. 

Only the current process is affected. 

None. Use _dos_getdrive to verify that the current drive was changed 
successfully. 

getcwd 




_dos_getfileattr 5 _dos_setf ileattr 



dos.h 



Function 
Syntax 



Remarks 



Changes file access mode. 

int _dos_getf ileattr (const char *path, unsigned *attribp) ; 
int _dos_setf ileattr (const char *path, unsigned attrib) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 








■ 



_dos_getfileattr fetches the file attributes for the file path. The attributes are 
stored at the location pointed to by attribp. 

_dos_setfileattr sets the file attributes for the file path to the value attrib. This 
function will fail (EACCES) if the file is currently open in any process. The 
file attributes can be an OR combination of the following symbolic 
constants (defined in dos.h): 



Return value 



_A_RDONLY Read-only attribute 

_A_HIDDEN Hidden file 

_A_SYSTEM System file 

_A_VOLID Volume label 

_A_SUBDIR Directory 

_A_ARCH Archive 

_A_NORMAL Normal file (no attribute bits set) 

Upon successful completion, _dos_getfileattr and _dos_setfileattr return 0. 
Otherwise, these functions return the operating system error code, and the 
global variable errno is set to 

ENOENT Path or file name not found 
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_d o s_g etf i I e att r, _d o s_s etf i I eatt r 



See also 



chmod, stat 



_dos_getftime, _dos_setftime 



dos.h 



Function 
Syntax 



Remarks 



Gets and sets file date and time. 

unsigned _dos_getftime(int handle, unsigned *datep, unsigned *timep) 
unsigned _dos_setftime(int handle, unsigned date, unsigned time); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 
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OS/2 


■ 




■ 








" 



_dos_getftime retrieves the file time and date for the disk file associated with 
the open handle. The file must have been previously opened using 
_dos_open, _dos_creat, or _dos_creatnew. _dos_getftime stores the date and 
time at the locations pointed to by datep and timep. 

jdosjsetftime sets the file's new date and time values as specified by date and 
time. The file must be open for writing; an EACCES error will occur if the 
file is open for read-only access. 

Note that the date and time values contain bit fields for referring to the file's 
date and time. The structure of these fields was established by the operat- 
ing system. 



Date: 




Bits 0-4 


Day 


Bits 5-8 


Month 


Bits 9-15 


Years since 1980 (for example, 9 here means 1989) 


Time: 




Bits 0-4 


The result of seconds divided by 2 (for example, 10 here 




means 20 seconds) 


Bits 5-10 


Minutes 


Bits 11-15 


Hours 



Return value _dos_getftime and _dos_setftime return on success. 

In the event of an error return, the operating system error code is returned 
and the global variable errno is set to one of the following values: 



See also 



EACCES 
EBADF 

fstat, stat 



Permission denied 
Bad file number 
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_dos_gettime, _dos_settime 



_dos_gettime, _dos_settime 



dos.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Gets and sets system time. 

void _dos_gettime (struct dostime_t *timep) ; 
unsigned _dos_settime( struct dostime_t *timep) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 
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■ 
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■ 



_dos_gettime fills in the dostimej structure pointed to by timep with the sys- 
tem's current time. 

_dos_settime sets the system time to the values in the dostimej, structure 
pointed to by timep. 

The dostimej. structure is defined as follows: 

struct dostimej { 

unsigned char hour; /* hours 0-23 */ 

unsigned char minute; /* minutes 0-59 */ 

unsigned char second; /* seconds 0-59 */ 

unsigned char hsecond; /* hundredths of seconds 0-99 */. 
}; 

_dos_gettime does not return a value. 

If _dos_settime is successful, it returns 0. Otherwise, it returns the operating 
system error code, and the global variable errno is set to: 

EINVAL Invalid time 

_dos_getdate, _dos_setdate, _dos_settime, stime, time 



_dos_open 



fcntl.h, share.h, dos.h 



Function 
Syntax 



Remarks 



Opens a file for reading or writing. 

unsigned _dos_open (const char *filename, unsigned oflags, int *handlep) ; 
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_dos_open opens the file specified by filename, then prepares it for reading or 
writing, as determined by the value of oflags. The file is always opened in 
binary mode. _dos_open stores the file handle at the location pointed to by 

handlep. 
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_dos_open 



These symbolic 
constants are defined 
in fcntl.h and share.h. 



Return value 



oflags uses the flags from the following two lists. Only one flag from the 
first list can be used (and one must be used); the remaining flags can be 
used in any logical combination. 

List 1 : Read/write flags 

0_RDONLY Open for reading. 
0_WRONLY Open for writing. 
0_RDWR Open for reading and writing. 

The following additional values can be included in oflags (using an OR 
operation): 

List 2: Other access flags 



O.NOINHERIT 

SH_COMPAT 

SH_DENYRW 

SH_DENWR 

SH_DENYRD 

SH DENYNO 



The file is not passed to child programs. 
Identical to SH_DENYNO. 

Only the current handle can have access to the file. 
Allow only reads from any other open to the file. 
Allow only writes from any other open to the file. 
Allow other shared opens to the file. 



Only one of the SH_DENYxx values can be included in a single _dos_open. 
These file-sharing attributes are in addition to any locking performed on 
the files. 

The maximum number of simultaneously open files is defined by 
HANDLE_MAX. 

On successful completion, _dos_open returns 0, and stores the file handle at 
the location pointed to by handlep. The file pointer, which marks the current 
position in the file, is set to the beginning of the file. 

On error, _dos_open returns the operating system error code. The global 
variable errno is set to one of the following: 



See also 



EACCES 
EINVACC 
EMFILE 
ENOENT 



Permission denied 
Invalid access code 
Too many open files 
Path or file not found 



open, _rtl_read, sopen 



dos read 



io.h, dos.h 



Function 



Reads from file. 
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dos read 



Syntax 



unsigned _dos_read(int handle, void *buf, unsigned len, unsigned *nread) ; 



Remarks 



Return value 
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_dos_read reads len bytes from the file associated with handle into buf. The 
actual number of bytes read is stored at the location pointed to by nread; 
when an error occurs, or the end-of-file is encountered, this number might 
be less than len. 

_dos_read does not remove carriage returns because it treats all hies as 
binary files. 

handle is a file handle obtained from a _dos_creat, _dos_creatnew, or _dos_open 
call. 

On disk files, _dos_read begins reading at the current file pointer. When the 
reading is complete, the function increments the file pointer by the number 
of bytes read. On devices, the bytes are read directly from the device. 

The maximum number of bytes that _dos_read can read is UINTJVIAX -1, 
because UINTJVIAX is the same as -1, the error return indicator. 
UINT_MAX is defined in limits.h. 

On successful completion, _dos_read returns 0. Otherwise, the function 
returns the DOS error code and sets the global variable errno. 




See also 



EACCES 
EBADF 



Permission denied 
Bad file number 



_rtl_open, read, _rtl_write 



dos setdate 



See _dos_getdate. 



dos setdrive 



See _dos_getdrive. 
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dos setftime 



dos setfileattr 



See _dos_getfileattr. 



dos setftime 



See _dos_getftime. 



dos settime 



See _dos_gettime. 



dos write 



dos.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Writes to a file. 

unsigned _dos_write(int handle, const void *buf, unsigned len, unsigned *nwritten) ; 
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_dos_write writes len bytes from the buffer pointed to by the pointer buf 'to 
the file associated with handle. _dos_write does not translate a linefeed 
character (LF) to a CR/LF pair because it treats all files as binary data. 

The actual number of bytes written is stored at the location pointed to by 
nwritten. If the number of bytes actually written is less than that requested, 
the condition should be considered an error and probably indicates a full 
disk. For disk files, writing always proceeds from the current file pointer. 
On devices, bytes are directly sent to the device. 

On successful completion, _dos_write returns 0. Otherwise, it returns the 
operating system error code and the global variable errno is set to one of the 
following values: 



EACCES 
EBADF 



Permission denied 
Bad file number 



_dos_open, _dos_creat, _dos_read 
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dostounix 



dostounix 

Function 
Syntax 



Remarks 



dos.h 



Return value 
See also 



Converts date and time to UNIX time format. 

long dostounix (struct date *d, struct time *t)-; 
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dostounix converts a date and time as returned from getdate and gettime into 
UNIX time format, d points to a date structure, and t points to a time 
structure containing valid date and time information. 

The date and time must not be earlier than or equal to Jan 1 1980 00:00:00. 

UNIX version of current date and time parameters: number of seconds 
since 00:00:00 on January 1, 1970 (GMT). 

getdate, gettime, unixtodos 




dup 



io.h 



Function 
Syntax 



Remarks 



Return value 



Duplicates a file handle. 

int dup(int handle); 
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dup creates a new file handle that has the following in common with the 
original file handle: 

b Same open file or device 

□ Same file pointer (that is, changing the file pointer of one changes the 
other) 

h Same access mode (read, write, read /write) 

handle is a file handle obtained from a _rtl_creat, creat, _rtl_open, open, dup, 
or dup2 call. 

Upon successful completion, dup returns the new file handle, a nonnegative 
integer; otherwise, dup returns -1. 

In the event of error, the global variable errno is set to one of the following 
values: 
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dup 



See also 



EBADF Bad file number 
EMFILE Too many open files 

_rtl_close, close, _rtl_creat, creat, creatnew, creattemp, dup2,fopen, _rtl_open, 
open 



dup2 



io.h 



Function 
Syntax 



Remarks 



Return value 



Duplicates a file handle (oldhandle) onto an existing file handle (newhandle). 

int dup2(int oldhandle, int newhandle); 
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dup2 creates a new file handle that has the following in common with the 
original file handle: 

■ Same open file or device 

■ Same file pointer (that is, changing the file pointer of one changes the 
other) 

■ Same access mode (read, write, read/write) 

dup2 creates a new handle with the value of newhandle. If the file associated 
with newhandle is open when dupl is called, the file is closed. 

newhandle and oldhandle are file handles obtained from a creat, open, dup, or 
dupl call. 

dupl returns on successful completion, -1 otherwise. 

In the event of error, the global variable errno is set to one of the following 
values: 



See also 



EBADF Bad file number 
EMFILE Too many open files 

_rtl_close, close, _rtl_creat, creat, creatnew, creattemp, dup,fopen, _rtl_open, open 



ecvt 



stdlib.h 



Function 
Syntax 



Converts a floating-point number to a string. 

char *ecvt (double value, int ndig, int *dec, int *sign) ; 
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ecvt 



Remarks 



Return value 
See also 
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ecvt converts value to a null-terminated string of ndig digits, starting with 
the leftmost significant digit, and returns a pointer to the string. The 
position of the decimal point relative to the beginning of the string is stored 
indirectly through dec (a negative value for dec means that the decimal lies 
to the left of the returned digits). There is no decimal point in the string 
itself. If the sign of value is negative, the word pointed to by sign is nonzero; 
otherwise, it's 0. The low-order digit is rounded. 

The return value of ecvt points to static data for the string of digits whose 
content is overwritten by each call to ecvt and fcvt. 

fcvt, gcvt, sprintf 




endthread 



process.h 



Function 
Syntax 



Terminates execution of a thread. 

void _endthread(void) ; 
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Remarks 



Return value 
See also 



The _endthread function terminates the currently executing thread. The 
thread must have been started by an earlier call to Jbeginthread. 

This function is available in C2MT.LIB, the multithread library; it is not in 
C2.LIB, the single-thread library. 

The function does not return a value. 

_beginthread 



eof 



io.h 



Function 
Syntax 



Checks for end-of-file. 

int eof (int handle) ; 
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eof 



Remarks 
Return value 



eof determines whether the file associated with handle has reached end-of- 
file. 

If the current position is end-of-file, eof returns the value 1; otherwise, it 
returns 0. A return value of -1 indicates an error; the global variable errno is 
set to 



See also 



EBADF Bad file number 

clear err , f eof , f error , perror 



execl, execle, execlp, execlpe, execv, execve, execvp, execvpe process.h 



Function 
Syntax 



Loads and runs other programs. 

int execl(char *path, char *argO *argl, .. 
int execle (char *path, char *argO, *argl, 

int execlp (char *path, char *argO,*argl, . 
int execlpe (char *path, char *argO, *argl, 



*argn, NULL) ; 

, *argn, NULL, char **env); 

*argn, NULL) ; 
. , *argn, NULL, char **env); 



int execvfchar *path, char *argv[]); 

int execve(char *path, char *argv[], char **env); 

int execvp(char *path, char *argv[]); 

int execvpe(char *path, char *argv[], char **env) ; 
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Remarks 



The functions in the exec. . . family load and run (execute) other programs, 
known as child processes. When an exec. . . call succeeds, the child process 
overlays the parent process. There must be sufficient memory available for 
loading and executing the child process. 

path is the file name of the called child process. The exec. . . functions search 
for path using the standard search algorithm: 

■ If no explicit extension is given, the functions search for the file as given. 
If the file is not found, they add .EXE and search again. If not found, they 
add .CMD and search again. If still not found, they add .BAT and search 
once more. The command processor (CMD.EXE) is used to run the 
executable file. 

■ If an explicit extension or a period is given, the functions search for the 
file exactly as given. 
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execl, execle, execlp, execlpe, execv, execve, execvp, execvpe 



The suffixes /, v, p, and e added to the exec. . . "family name" specify that the 
named function operates with certain capabilities. 

■ / specifies that the argument pointers (argO, argl, ..., argn) are passed as 
separate arguments. Typically, the / suffix is used when you know in 
advance the number of arguments to be passed. 

n v specifies that the argument pointers (argv[0] ..., arg[n]) are passed as an 
array of pointers. Typically/the v suffix is used when a variable number 
of arguments is to be passed. 

■ p specifies that the function searches for the file in those directories 
specified by the PATH environment variable (without the p suffix, the 
function searches only the current working directory). If the path parame- 
ter does not contain an explicit directory, the function searches first the 
current directory, then the directories set with the PATH environment 
variable. 

n e specifies that the argument env can be passed to the child process, 
letting you alter the environment for the child process. Without the e 
suffix, child processes inherit the environment of the parent process. 

Each function in the exec. . . family must have one of the two argument- 
specifying suffixes (either / or v). The path search and environment 
inheritance suffixes (p and e) are optional; for example, 

m execl is an exec... function that takes separate arguments, searches only 
the root or current directory for the child, and passes on the parent's 
environment to the child. 

■ execvpe is an exec. . . function that takes an array of argument pointers, 
incorporates PATH in its search for the child process, and accepts the env 
argument for altering the child's environment. 

The exec. . . functions must pass at least one argument to the child process 
(argO or argv[0]); this argument is, by convention, a copy of path. (Using a 
different value for this Oth argument won't produce an error.) 

When the / suffix is used, argO usually points to path, and argl, ..., argn 
point to character strings that form the new list of arguments. A mandatory 
null following argn marks the end of the list. 

When the e suffix is used, you pass a list of new environment settings 
through the argument env. This environment argument is an array of 
character pointers. Each element points to a null-terminated character 
string of the form 

envvar = value 

where envvar is the name of an environment variable, and value is the string 
value to which envvar is set. The last element in env is null. When env is 
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execl, execle, execlp, execlpe, execv, execve, execvp, execvpe 



null, the child inherits the parents' environment settings. When an exec. 
function call is made, any open files remain open in the child process. 

Return value if successful, the exec. . . functions do not return. On error, the exec. . . 

functions return -1, and the global variable errno is set to one of the 
following values: 



See also 



EACCES Permission denied 

EMFILE Too many open files 

ENOENT Path or file name not found 

ENOEXEC Exec format error 

ENOMEM Not enough memory 

abort, atexit, _exit, exit, Jpreset, searchpath, spawn..., system 



exit 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Terminates program. 

void _exit(int status); 
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_exit terminates execution without closing any files, flushing any output, or 
calling any exit functions. 

The calling process uses status as the exit status of the process. Typically a 
value of is used to indicate a normal exit, and a nonzero value indicates 
some error. 

None. 

abort, atexit, exec. . ., exit, spawn.. . 



exit 



stdlib.h 



Function 
Syntax 



Terminates program. 

void exit(int status); 
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exit 



Remarks 



exit terminates the calling process. Before termination, all files are closed, 
buffered output (waiting to be output) is written, and any registered "exit 
functions" (posted with atexit) are called. 

status is provided for the calling process as the exit status of the process. 
Typically a value of is used to indicate a normal exit, and a nonzero value 
indicates some error. It can be, but is not required, to be set with one of the 
following: 




Return value 
See also 



EXIT_FAILURE Abnormal program termination; signal to operating 

system that program has terminated with an error 
EXIT_SUCCESS Normal program termination 

None. 

abort, atexit, exec. .., _exit, signal, spawn. . . 



exp, expl 



math.h 



Function 
Syntax 



exp 
expl 



Remarks 



Return value 



Calculates the exponential e to the x. 

double exp(double x) ; 

long double expl (long double x) ; 
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exp calculates the exponential function e x . 

expl is the long double version; it takes a long double argument and returns 
a long double result. 

This function can be used with bed and complex types. 

exp returns e x . 

Sometimes the arguments passed to these functions produce results that 
overflow or are incalculable. When the correct value overflows, exp returns 
the value HUGE_VAL and expl returns _LHUGE_VAL. Results of exces- 
sively large magnitude cause the global variable errno to be set to 

ERANGE Result out of range 
On underflow, these functions return 0.0, and the global variable errno is 
not changed. Error handling for these functions can be modified through 
the functions matherr and matherrl. 
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exp, expl 



See also 

_expand 



frexp, Idexp, log, loglO, jnatherr, pow, powlO, sort 



malloc.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Grows or shrinks a heap block in place. 

void *_expand(void *block, size_t size); 
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This function attempts to change the size of an allocated memory block 
without moving the block's location in the heap. The data in the block are 
not changed, up to the smaller of the old and new sizes of the block. The 
block must have been allocated earlier with malloc, calloc, or realloc, and 
must not have been freed. 

If _expand is able to resize the block without moving it, _expand returns a 
pointer to the block, whose address is unchanged. If _expand is unsuccess- 
ful, it returns a NULL pointer and does not modify or resize the block. 

calloc, malloc, realloc 



tabs, fabsl 



math.h 



Function 
Syntax 



tabs 
tabsl 



Remarks 

Return value 
See also 



Returns the absolute value of a floating-point number. 



double fabs (double x) ; 

long double fabsl (long double x) ; 
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fabs calculates the absolute value of x, a double, fabsl is the long double 
version; it takes a long double argument and returns a long double result. 

fabs and fabsl return the absolute value of x. 

abs, cabs, labs 
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fclose 



fclose 

Function 
Syntax 



Remarks 



Return value 
See also 



stdio.h 



Closes a stream. 

int fclose (FILE *stream) ; 
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fclose closes the named stream. All buffers associated with the stream are 
flushed before closing. System-allocated buffers are freed upon closing. 
Buffers assigned with setbufoi setvbuf are not automatically freed. (But if 
setvbuf is passed null for the buffer pointer, it will free it upon close.) 

fclose returns on success. It returns EOF if any errors were detected. 

close, fcloseall, fdopen, fflush, flushall, fopen, j reopen 



fcloseall 



stdio.h 



Function 
Syntax 



Closes open streams. 

int fcloseall (void) ; 
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Remarks 
Return value 
See also 



fcloseall closes all open streams except stdin, stdout, stdprn, stderr, and 
stdaux. stdprn and stdaux streams are not available on OS/2. 

fcloseall returns the total number of streams it closed. It returns EOF if any 
errors were detected. 

fclose, fdopen, flushall, fopen, f reopen . 



fcvt 



stdlib.h 



Function 
Syntax 



Converts a floating-point number to a string. 

char *fcvt (double value, int ndig, int *dec, int *sign) ; 
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fcvt 



Remarks 



Return value 
See also 
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fcvt converts value to a null-terminated string digit, starting with the 
leftmost significant digit, with ndig digits to the right of the decimal point. 
fcvt then returns a pointer to the string. The position of the decimal point 
relative to the beginning of the string is stored indirectly through dec (a 
negative value for dec means to the left of the returned digits). There is no 
decimal point in the string itself. If the sign of value is negative, the word 
pointed to by sign is nonzero; otherwise, it is 0. 

The correct digit has been rounded for the number of digits to the right of 
the decimal point specified by ndig. 

The return value of fcvt points to static data whose content is overwritten 
by each call to fcvt and ecvt. 

ecvt, gcvt, sprintf 



fdopen 



stdio.h 



Function 
Syntax 



Remarks 



Associates a stream with a file handle. 

FILE *fdopen(int handle, char *type) ; 
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fdopen associates a stream with a file handle obtained from creat, dup, dup2, 
or open. The type of stream must match the mode of the open handle. 

The type string used in a call to fdopen is one of the following values: 



Value 



Description 



r Open for reading only. 

w Create for writing. 

a Append; open for writing at end-of-file, or create for writing if the file does not exist. 

r+ Open an existing file for update (reading and writing). 

w+ Create a new file for update. 

a+ Open for append; open (or create if the file does not exist) for update at the end of 
the file. 
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fdopen 



Return value 
See also 



To specify that a given file is being opened or created in text mode, append 
a t to the value of the type string (rt, w+t, and so on); similarly, to specify 
binary mode, append a b to the type string (zvb, a+b, and so on). 

If a t or b is not given in the type string, the mode is governed by the global 
variable Jmode. If Jmode is set to 0_BINARY, files will be opened in binary 
mode. If Jmode is set to 0_TEXT, they will be opened in text mode. These 
0_. . . constants are defined in fcntl.h. 

When a file is opened for update, both input and output can be done on the 
resulting stream. However, output cannot be directly followed by input 
without an intervening/see/: or rewind, and input cannot be directly 
followed by output without an intervening fseek, rewind, or an input that 
encounters end-of-file. 

On successful completion, fdopen returns a pointer to the newly opened 
stream. In the event of error, it returns NULL. 

f close, f open, freopen, open 




feof 



stdio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Detects end-of-file on a stream. 

int feof (FILE *stream) ; 
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feof is a macro that tests the given stream for an end-of-file indicator. Once 
the indicator is set, read operations on the file return the indicator until 
rewind is called, or the file is closed. 

The end-of-file indicator is reset with each input operation. 

feof returns nonzero if an end-of-file indicator was detected on the last input 
operation on the named stream, and if end-of-file has not been reached. 

clear err, eoff error, perror 



terror 



stdio.h 



Function 
Syntax 



Detects errors on stream. 

int f error (FILE *stream) ; 
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terror 



Remarks 

Return value 
See also 
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fervor is a macro that tests the given stream for a read or write error. If the 
stream's error indicator has been set, it remains set until clearerr or rewind is 
called, or until the stream is closed. 

ferror returns nonzero if an error was detected on the named stream. 

clearerr, eof,feof,fopen, gets, perror 



fflush 



stdio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Flushes a stream. 

int fflush (FILE *stream) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


" | 


■ 


■ 


■ 



If the given stream has buffered output, fflush writes the output for stream 
to the associated file. 

The" stream remains open after fflush has executed, fflush has no effect on an 
unbuffered stream. 

fflush returns on success. It returns EOF if any errors were detected. 

f close, flushall, setbuf setvbuf 



fgetc 



stdio.h 



Function 
Syntax 



Remarks 
Return value 

See also 



Gets character from stream. 

int fgetc (FILE *stream) ; 
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fgetc returns the next character on the named input stream. 

On success, fgetc returns the character read, after converting it to an int 
without sign extension. On end-of-file or error, it returns EOF. 

fgetchar,fputc, getc, getch, getchar, getche, ungetc, ungetch 
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fgetchar 



fgetchar 

Function 
Syntax 



Remarks 
Return value 

See also 



stdio.h 



Gets character from stdin. 

int fgetchar (void) ; 
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fgetchar returns the next character from stdin. It is defined as fgetc(stdin). 

On success, fgetchar returns the character read, after converting it to an int 
without sign extension. On end-of-file or error, it returns EOF. 

fgetc, fputchar, freopen, getchar 




fgetpos 



stdio.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Gets the current file pointer. 

int fgetpos (FILE *stream, fpos_t *pos) ; 
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fgetpos stores the position of the file pointer associated with the given 
stream in the location pointed to by pos. The exact value is unimportant; its 
value is opaque except as a parameter to subsequent fsetpos calls. 

On success, fgetpos returns 0. On failure, it returns a nonzero value and sets 
the global variable errno to 



EBADF 
EINVAL 

f seek, fsetpos, f tell, tell 



Bad file number 
Invalid number 



fgets 



stdio.h 



Function 
Syntax 



Gets a string from a stream. 

char *fgets(char *s, int n, FILE *stream) ; 
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fgets 



Remarks 

Return value 
See also 
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fgets reads characters from stream into the string s. The function stops 
reading when it reads either n - 1 characters or a newline character, which- 
ever comes first, fgets retains the newline character at the end of s. A null 
byte is appended to s to mark the end of the string. 

On success, ^gefs returns the string pointed to by s; it returns NULL on 
end-of-file or error. 

cgets,fputs,gets 



filelength 



io.h 



Function 
Syntax 



Remarks 
Return value 



See also 



Gets file size in bytes. 

long filelength (int handle); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



filelength returns the length (in bytes) of the file associated with handle. 

On success, filelength returns a long value, the file length in bytes. On error, 
it returns -1 and the global variable errno is set to 



EBADF Bad file number 

fopen, Iseek, open 



fileno 



stdio.h 



Function 
Syntax 



Remarks 



Gets file handle. 

int fileno (FILE *stream) ; 
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fileno is a macro that returns the file handle for the given stream. If stream 
has more than one handle, fileno returns the handle assigned to the stream 
when it was first opened. 
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fileno 



Return value 
See also 



fileno returns the integer file handle associated with stream, 
f dopen, fopen, freopen 



findfirst 



dir.h 



Function 
Syntax 



Remarks 



Searches a disk directory. 

int findfirst (const char *pathname, struct ffblk *ffblk, int attrib) 
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findfirst begins a search of a disk directory for files specified by attributes or 
wildcards. 

pathname is a string with an optional drive specifier, path, and file name of 
the file to be found. Only the file name portion can contain wildcard match 
characters (such as ? or *). If a matching file is found, the ffblk structure is 
filled with the file-directory information. 

The format of the structure ffblk is as follows: 



struct ffblk { 








long 


ff_reserved; 






long 


ff_fsize; 


/* 


file size */ 


unsigned long 


ff_attrib; 


/* 


attribute found */ 


unsigned short 


ff_ftime; 


/* 


file time */ 


unsigned short 


ff_fdate; 


/* 


file date */ 


char 


ff_name[256]; 


/* 


found file name */ 



attrib is a file-attribute byte used in selecting eligible files for the search. 
attrib should be selected from the following constants defined in dos.h: 



FA_RDONLY 
FAJHIDDEN 
FA_SYSTEM 
FA DIREC 



Read-only attribute 
Hidden file 
System file 
Directory 



A combination of constants can be ORed together. 

For more detailed information about these attributes, refer to your operat- 
ing system reference manuals. 
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findfirst 



Return value 



Note that ffjtime and ffjdate contain bit fields for referring to the current 
date and time. The structure of these fields was established by the operat- 
ing system. Both are 16-bit structures divided into three fields. 



ffjtime: 

Bits to 4 

Bits 5 to 10 
Bits 11 to 15 



The result of seconds divided by 2 (for example, 10 here 

means 20 seconds) 

Minutes 

Hours 



ffjdate: 

Bits 0-4 
Bits 5-8 
Bits 9-15 



Day 

Month 

Years since 1980 (for example, 9 here means 1989) 

The structure ftime declared in io.h uses time and date bit fields similar in 
structure to ff_ftime, and ff_fdate. 

findfirst returns on successfully finding a file matching the search 
■pathname. When no more files can be found, or if there is some error in the 
file name, -1 is returned, and the global variable errno is set to 



See also 



ENOENT Path or file name not found 

and _doserrno is set to one of the following values: 

ENMFILE No more files 

ENOENT Path or file name not found 

findnext, getftime, setftime 



findnext 



dir.h 



Function 
Syntax 



Remarks 



Continues findfirst search. 

int findnext (struct ffblk *f fblk) ; 
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findnext is used to fetch subsequent files that match the pathname given in 
findfirst. ffblk is the same block filled in by the findfirst call. This block 
contains necessary information for continuing the search. One file name for 
each call to findnext will be returned until no more files are found in the 
directory matching the pathname. 
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findnext 



Return value findnext returns on successfully finding a file matching the search 

pathname. When no more files can be found, or if there is some error in the 
file name, -1 is returned, and the global variable errno is set to 



See also 



ENOENT Path or file name not found 
and jioserrno is set to one of the following values: 
ENMFILE No more files 



ENOENT 
findfirst 



Path or file name not found 



floor, f loorl 



math.h 



Function 
Syntax 



Remarks 
Return value 
See also 



floor 
floorl 



Rounds down. 

double floor (double x) ; 

long double floorl (long double x) ; 
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floor finds the largest integer not greater than x. floorl is the long double 
version; it takes a long double argument and returns a long double result. 

floor returns the integer found as a double./Zoor/ returns the integer found 
as a long double. 

ceil, f mod 



flushall 



stdio.h 



Function 
Syntax 



Remarks 



Flushes all streams. 

int flushall (void) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


i 


■ 






■ 



flushall clears all buffers associated with open input streams, and writes all 
buffers associated with open output streams to their respective files. Any 
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flushall 



Return value 
See also 



read operation following flushall reads new data into the buffers from the 
input files. Streams stay open after flushall executes. 

flushall returns an integer, the number of open input and output streams. 

f close, fcloseall, jflush 



fmod, fmodl 



math.h 



Function 
Syntax 



fmod 
fmodl 



Calculates x modulo y, the remainder of x/y. 

double fmod(double x, double y) ; 

long double fmodl (long double x, long double y); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 


■ 




■ 


■ 






■ 



Remarks 

Return value 
See also 



fmod calculates x modulo y (the remainder/, where x = ay +/for some 
integer a and </< y). fmodl is the long double version; it takes long 
double arguments and returns a long double result. 

fmod and fmodl return the remainder/, where x = ay +/(as described). 
Where y = 0,fmod and fmodl return 0. 

ceil, floor, modf 



fnmerge 



dir.h 



Function 
Syntax 



Remarks 



Builds a path from component parts. 

void fnmerge (char *path, const char * drive, const char *dir, const char *name, 
const char *ext) ; 
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fnmerge makes a path name from its components. The new path name is 

X:\DIR\SUBDIR\NAME.EXT 

where 



drive = X: 
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fnmerge 



Return value 
See also 



dir = \DIR\SUBDIR\ 
name = NAME 
ext = .EXT 

fnmerge assumes there is enough space in path for the constructed path 
name. The maximum constructed length is MAXPATH. MAXPATH is 
defined in dir.h. 

fnmerge and fnsplit are invertible; if you split a given path with fnsplit, then 
merge the resultant components with fnmerge, you end up with path. 

None. 

fnsplit 




fnsplit 



dir.h 



Function 
Syntax 



Remarks 



Splits a full path name into its components. 

int fnsplit (const char *path, char *drive, char *dir, char *name, char *ext) 
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fnsplit takes a file's full path name (path) as a string in the form 

X:\DIR\SUBDIR\NAME.EXT 

and splits path into its four components. It then stores those components in 
the strings pointed to by drive, dir, name, and ext. All five components must 
be passed, but any of them can be a null, which means the corresponding 
component will be parsed but not stored. If any path component is null, 
that component corresponds to a non-NULL, empty string. 

The maximum sizes for these strings are given by the constants MAXDRIVE, 
MAXDIR, MAXPATH, MAXFILE, and MAXEXT (defined in dir.h), and each size 
includes space for the null character. 



Constant 



Max 



String 



MAXPATH 


260 


path 


MAXDRIVE 


3 


drive; includes colon (:) 


MAXDIR 


256 


dir, includes leading and trailing backslashes (\) 


MAXFILE 


256 


name 


MAXEXT 


256 


ext, includes leading dot (.) 



fnsplit assumes that there is enough space to store each non-null 
component. 
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fnsplit 



Return value 



When fnsplit splits path, it treats the punctuation as follows: 

a drive includes the colon (C:, A:, and so on). 

□ dir includes the leading and trailing backslashes ( \ BC\ include \, 
\ source \, and so on). 

b name includes the file name. 

d ext includes the dot preceding the extension (.C, .EXE, and so on). 

fnmerge and fnsplit are invertible; if you split a given path with fnsplit, then 
merge the resultant components with fnmerge, you end up with path. 

fnsplit returns an integer (composed of five flags, defined in dir.h) 
indicating which of the full path name components were present in path. 
These flags and the components they represent are 



See also 



EXTENSION 

FILENAME 

DIRECTORY 

DRIVE 

WILDCARDS 



fnmerge 



An extension 

A file name 

A directory (and possibly subdirectories) 

A drive specification (see dir.h) 

Wildcards (* or ?) 



fopen 



stdio.h 



Function 
Syntax 



Remarks 



Opens a stream. 

FILE *fopen(const char *filename, const char *mode) ; 
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fopen opens the file named by filename and associates a stream with it. fopen 
returns a pointer to be used to identify the stream in subsequent 
operations. 

The mode string used in calls to fopen is one of the following values: 



Value 



Description 



r Open for reading only. 

w Create for writing. If a file by that name already exists, it will be overwritten. 

a Append; open for writing at end of file, or create for writing if the file does not exist. 

r+ Open an existing file for update (reading and writing). 
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fopen 



Return value 
See also 



w+ 



a+ 



Create a new file for update (reading and writing). If a file by that name already 
exists, it will be overwritten. 

Open for append; open for update at the end of the file, or create if the file does not 
exist. 



To specify that a given file is being opened or created in text mode, append 
a t to the mode string (rt, w+t, and so on). Similarly, to specify binary mode, 
append a b to the mode string (wb, a+b, and so on), fopen also allows the t or 
b to be inserted between the letter and the + character in the mode string; 
for example, rt+ is equivalent to r+t. 

If a t or b is not given in the mode string, the mode is governed by the global 
variable Jmode. If Jmode is set to 0_BINARY, files are opened in binary 
mode. If Jmode is set to 0_TEXT, they are opened in text mode. These 0_. . . 
constants are defined in fcntl.h. 

When a file is opened for update, both input and output can be done on the 
resulting stream. However, output cannot be followed directly by input 
without an intervening fseek or rewind, and input cannot be directly 
followed by output without an intervening fseek, rewind, or an input that 
encounters end-of-file. 

On successful completion, fopen returns a pointer to the newly opened 
stream. In the event of error, it returns NULL. 

creat, dup,f close, fdopenf error, Jmode (global variable), freadjreopen, fseek, 
fwrite, open, rewind, setbuf setmode 




Jpreset 



float.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Reinitializes floating-point math package. 



void _fpreset (void) ; 
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Jpreset reinitializes the floating-point math package. This function is 
usually used in conjunction with system or the exec. . . or spawn. . . functions. 
It is also used to recover from floating-point errors before calling longjmp. 

None. 

_clear87, _control87, _status87 
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fprintf 



fprintf 

Function 
Syntax 



Remarks 



See printf for details 
on format specifiers. 

Return value 



See also 



stdio.h 



Writes formatted output to a stream. 

int fprintf (FILE *stream, const char *format[, argument, . 
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fprintf accepts a series of arguments, applies to each a format specifier 
contained in the format string pointed to by format, and outputs the 
formatted data to a stream. There must be the same number of format 
specifiers as arguments. 

fprintf returns the number of bytes output. In the event of error, it returns 
EOF. 

cprintf fscanf, printf, putc, sprintf 



fputc 



stdio.h 



Function 
Syntax 



Remarks 
Return value 
See also 



Puts a character on a stream. 

int fputc (int c, FILE *stream) ; 
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fputc outputs character c to the named stream. 

On success, fputc returns the character c. On error, it returns EOF. 

fgetc, putc 



fputchar 



stdio.h 



Function 
Syntax 



Outputs a character on stdout. 

int fputchar (int c) ; 
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fputchar 



Remarks 

Return value 
See also 

fputs 



fputchar outputs character c to stdout fpu tchar(c) is the same as 
fputcic, stdout). 

This function should not be used in PM applications. 

On success, fputchar returns the character c. On error, it returns EOF. 

fgetchar,freopen, putchar 



stdio.h 




Function 
Syntax 



Remarks 

Return value 
See also 



Outputs a string on a stream. 

int fputs (const char *s, FILE * stream) ; 
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fputs copies the null-terminated string s to the given output stream; it does 
not append a newline character, and the terminating null character is not 
copied. 

On successful completion, fputs returns a non-negative value. Otherwise, it 
returns a value of EOF. 

fgets, gets, puts 



fread 



stdio.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Reads data from a stream. 

size_t freadfvoid *ptr, size_t size, size_t n, FILE * stream) ; 
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fread reads n items of data, each of length size bytes, from the given input 
stream into a block pointed to by ptr. 

The total number of bytes read is (n x size). 

On successful completion, fread returns the number of items (not bytes) 
actually read. It returns a short count (possibly 0) on end-of-file or error. 

fopen,fwrite, printf read 
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free 



free 

Function 
Syntax 



Remarks 

Return value 
See also 



stdlib.h 



Frees allocated block. 

void free (void *block) ; 
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free deallocates a memory block allocated by a previous call to calloc, malloc, 
or realloc. 

None. 

calloc, malloc, realloc, strdup 



freopen 



stdio.h 



Function 
Syntax 



Remarks 



Associates a new file with an open stream. 

FILE * freopen (const char * filename, const char *mode, FILE *stream) 
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freopen substitutes the named file in place of the open stream. It closes 
stream, regardless of whether the open succeeds, freopen is useful for 
changing the file attached to stdin, stdout, or stderr. 

The mode string used in calls tofopen is one of the following values: 



Value 



Description 



Open for reading only. 

Create for writing. 

Append; open for writing at end-of-file, or create for writing if the file does not exist. 

Open an existing file for update (reading and writing). 

Create a new file for update. 



r 

w 

a 

r+ 

w+ 

a+ 



Open for append; open (or create if the file does not exist) for update at the end of 
the file. 



To specify that a given file is being opened or created in text mode, append 
a t to the mode string (rt, w+t, and so on); similarly, to specify binary mode, 
append a b to the mode string (wb, a+b, and so on). 
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freopen 



Return value 
See also 



If a t or b is not given in the mode string, the mode is governed by the global 
variable Jmode. If Jmode is set to 0_BINARY, files are opened in binary 
mode. If Jmode is set to OJTEXT, they are opened in text mode. These 0_. . . 
constants are defined in fcntl.h. 

When a file is opened for update, both input and output can be done on the 
resulting stream. However, output cannot be directly followed by input 
without an intervening/see/c or rewind, and input cannot be directly 
followed by output without an intervening fseek, rewind, or an input that 
encounters end-of-file. 

On successful completion, freopen returns the argument stream. In the event 
of error, it returns NULL. 

f close, fdopen, fopen, open, setmode 




frexp, frexpl 



math.h 



Function 
Syntax 



Remarks 



frexp 
frexpl 



Return value 



See also 



Splits a number into mantissa and exponent. 



double frexp (double x, int ^exponent); 
long double frexpl (long double x, int 



* exponent) 
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frexp calculates the mantissa m (a double greater than or equal to 0.5 and 
less than 1) and the integer value n, such that x (the original double value) 
equals m x 2 n . frexp stores n in the integer that exponent points to. 

frexpl is the long double version; it takes a long double argument for x and 
returns a long double result. 

frexp and frexpl return the mantissa m. Error handling for these routines can 
be modified through the functions jnatherr and jnatherrl. 

exp, Idexp, jnatherr 



fscanf 



stdio.h 



Function 
Syntax 



Scans and formats input from a stream. 

int fscanf (FILE *stream, const char * format [, address, 
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fscanf 



Remarks 

See scant for details 
on format specifiers. 



Return value 
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See also 



fscanf scans a series of input fields, one character at a time, reading from a 
stream. Then each field is formatted according to a format specifier passed 
to fscanf in the format string pointed to by format. Finally, fscanf stores the 
formatted input at an address passed to it as an argument following/ormaf. 
The number of format specifiers and addresses must be the same as the 
number of input fields. 

fscanf can stop scanning a particular field before it reaches the normal end- 
of-field character (whitespace), or it can terminate entirely for a number of 
reasons. See scanf for a discussion of possible causes. 

fscanf returns the number of input fields successfully scanned, converted, 
and stored; the return value does not include scanned fields that were not 
stored. 

If fscanf attempts to read at end-of-file, the return value is EOF. If no fields 
were stored, the return value is 0. 

atof cscanffprintf printf scanf, sscanf, vf scanf, vscanf vsscanf 



fseek 



stdio.h 



Function 
Syntax 



Remarks 



Repositions a file pointer on a stream. 

int fseek(FILE *stream, long offset, int whence); 
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fseek sets the file pointer associated with stream to a new position that is 
offset bytes from the file location given by whence. For text mode streams, 
offset should be or a value returned by ftell. 

whence must be one of the values 0, 1, or 2, which represent three symbolic 
constants (defined in stdio.h) as follows: 



Constant 



whence 



File location 



SEEK_SET 
SEEK_CUR 
SEEK END 



File beginning 

1 Current file pointer position 

2 End-of-file 
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fseek 



Return value 



See also 



fseek discards any character pushed back using ungetc. fseek is used with 
stream I/O; for file handle I/O, use Iseek. 

After fseek, the next operation on an update file can be either input or 
output. 

fseek returns if the pointer is successfully moved and nonzero on failure. 

In the event of an error return, the global variable errno is set to one of the 
following values: 

EBADF Bad file pointer 

EINVAL Invalid argument 
ESPIPE Illegal seek on device 

fgetpos, fopen, fsetpos, f tell, Iseek, rewind, setbuf tell 




fsetpos 



stdio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Positions the file pointer of a stream. 

int fsetpos (FILE *stream, const fpos_t *pos) ; 
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fsetpos sets the file pointer associated with stream to a new position. The 
new position is the value obtained by a previous call to fgetpos on that 
stream. It also clears the end-of-file indicator on the file that stream points to 
and undoes any effects of ungetc on that file. After a call to fsetpos, the next 
operation on the file can be input or output. 

On success, fsetpos returns 0. On failure, it returns a nonzero value and also 
sets the global variable errno to a nonzero value. 

fgetpos, fseek, f tell 



Jsopen 



stdio.h, share.h 



Function 
Syntax 



Opens a stream with file sharing. 

FILE *_fsopen (const char *filename, const char *mode, int shflag) 
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Jsopen 



Remarks Jsopen opens the file named by filename and associates a stream with it. 

Jsopen returns a pointer that is used to identify the stream in subsequent 
operations. 

The mode string used in calls to Jsopen is one of the following values: 



Mode Description 

r Open for reading only. 

w Create for writing. If a file by that name already exists, it will be overwritten. 

a Append; open for writing at end of file, or create for writing if the file does not exist. 

r+ Open an existing file for update (reading and writing). 

w+ Create a new file for update (reading and writing). If a file by that name already 

exists, it will be overwritten. 

a+ Open for append; open for update at the end of the file, or create if the file does not 

exist. 

To specify that a given file is being opened or created in text mode, append 
a t to the mode string (rt, iv+t, and so on). Similarly, to specify binary mode, 
append a b to the mode string (w b, a+b, and so on). Jsopen also allows the t 
or b to be inserted between the letter and the + character in the mode string; 
for example, rt+ is equivalent to r+t. 

If a t or b is not given in the mode string, the mode is governed by the global 
variable Jmode. If Jmode is set to 0_BINARY, files are opened in binary 
mode. If Jmode is set to OJTEXT, they are opened in text mode. These 0_. . . 
constants are defined in fcntl.h. 

When a file is opened for update, both input and output can be done on the 
resulting stream. However, output cannot be followed directly by input 
without an intervening fseek or rewind, and input cannot be directly 
followed by output without an intervening fseek, rewind, or an input that 
encounters end-of-file. 

shflag specifies the type of file-sharing allowed on the file filename. Symbolic 
constants for shflag are defined in share.h. 



Value of shflag Description 



SH_COMPAT Sets compatibility mode 

SH DENYRW Denies read/write access 



SH DENYWR Denies write access 
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Return value 
See also 

fstat, stat 



SH_DENYRD 
SH_DENYNONE 
SH DENYNO 



Denies read access 
Permits read/write access 
Permits read/write access 



On successful completion, Jsopen returns a pointer to the newly opened 
stream. In the event of error, it returns NULL. 

creat, _dos_open, dup,f close, fdopen,f error, Jrnode (global variable), } open, 
fread, f reopen, fseek, fwrite, open, rewind, setbuf, setmode, sopen 




sys\stat.h 



Function 
Syntax 



Remarks 



Gets open file information. 

int fstat (int handle, struct stat *statbuf ) ; 
int stat (char *path, struct stat *statbuf); 
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fstat stores information in the stat structure about the file or directory 
associated with handle. 

stat stores information about a given file or directory in the stat structure. 
The name of the file is path. 

statbuf points to the stat structure (defined in sys\stat.h). That structure 
contains the following fields: 

stjnode Bit mask giving information about the file's mode 

st_dev Drive number of disk containing the file, or file handle if the 
file is on a device 

st_rdev Same as st_dev 

st_nlink Set to the integer constant 1 

st_size Size of the file in bytes 

st_atime Most recent time the file was modified 

stjntime Same as st_atime 

st_ctime Same as st_atime 

The stat structure contains three more fields not mentioned here. They 
contain values that are meaningful only in UNIX. 
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fstat, stat 



Return value 



See also 



The stjnode bit mask that gives information about the mode of the open file 
includes the following bits: 

One of the following bits will be set: 

S_IFCHR If handle refers to a device. 

S_IFREG If an ordinary file is referred to by handle. 

One or both of the following bits will be set: 

S_IWRITE If user has permission to write to file. 
S_IREAD If user has permission to read to file. 

fstat and stat return if they successfully retrieved the information about 
the open file. On error (failure to get the information), these functions 
return -1 and set the global variable errno to 



EBADF 

access, chmod 



Bad file handle 



ftell 



stdio.h 



Function 
Syntax 



Remarks 



Return value 



Returns the current file pointer. 

long int ftell (FILE *stream) ; 
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See also 



ftell returns the current file pointer for stream. The offset is measured in 
bytes from the beginning of the file (if the file is binary). The value returned 
by ftell can be used in a subsequent call to fseek. 

ftell returns the current file pointer position on success. It returns -1L on 
error and sets the global variable errno to a positive value. 

In the event of an error return, the global variable errno is set to one of the 
following values: 

EBADF Bad file pointer 

ESPIPE Illegal seek on device 

fgetpos, fseek, fsetpos, Iseek, rewind, tell 
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ftime 

Function 
Syntax 



Remarks 



sys\timeb.h 



Return value 
See also 



Stores current time in timeb structure. 

void ftime (struct timeb *buf) 
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On UNIX platforms, fti me is available only on System V systems. 

ftime determines the current time and fills in the fields in the timeb structure 
pointed to by buf. The timeb structure contains four fields: time, millitm, 
Jimezone, and dstflag: 

struct timeb { 

long time ; 

short millitm ; 

short _timezone ; 

short dstflag ; 
}; 

■ time provides the time in seconds since 00:00:00 Greenwich mean time 
(GMT), January 1, 1970. 

■ millitm is the fractional part of a second in milliseconds. 

■ Jimezone is the difference in minutes between GMT and the local time. 
This value is computed going west from GMT. ftime gets this field from 
the global variable Jimezone, which is set by tzset. 

a dstflag is used to indicate whether daylight saving time will be taken into 
account during time calculations. 

ftime calls tzset. Therefore, it isn't necessary to call tzset explicitly when you 
use ftime. 

None. 

asctime, ctime, gmtime, localtime, stime, time, tzset 



Jullpath 



stdlib.h 



Function 
Syntax 



Converts a path name from relative to absolute. 

char * _fullpath(char *buffer, const char *path, int buflen) ; 
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Jullpath 



Remarks 



Return value 
See also 
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Jullpath converts the relative path name in -path to an absolute path name 
that is stored in the array of characters pointed to by buffer. The maximum 
number of characters that can be stored at buffer is buflen. The function 
returns NULL if the buffer isn't big enough to store the absolute path name, 
or if the path contains an invalid drive letter. 

If buffer is NULL, Jullpath allocates a buffer of up to _MAX_PATH charac- 
ters. This buffer should be freed using free when it is no longer needed. 
_MAX_PATH is defined in stdlib.h 

If successful, the Jullpath function returns a pointer to the buffer containing 
the absolute path name. Otherwise, it returns NULL. 

jnakepath, _splitpath 



fwrite 



stdio.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Writes to a stream. 

size_t fwrite (const void *ptr, size_t size, size_t n, FILE *stream) 
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fwrite appends n items of data, each of length size bytes, to the given output 
file. The data written begins at ptr. The total number of bytes written is (n x 
size), ptr in the declarations is a pointer to any object. 

On successful completion, fwrite returns the number of items (not bytes) 
actually written. It returns a short count on error. 

fopen, fread 



gcvt 



stdlib.h 



Function 
Syntax 



Converts floating-point number to a string. 

char *gcvt (double value, int ndec, char *buf); 
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Remarks 



Return value 
See also 



getc 



gcvt converts value to a null-terminated ASCII string and stores the string in 
buf. It produces ndec significant digits in FORTRAN F format, if possible; 
otherwise, it returns the value in the printfE format (ready for printing). It 
might suppress trailing zeros. 

gcvt returns the address of the string pointed to by buf 

ecvt,fcvt, sprintf 

stdio.h 




Function 
Syntax 



Remarks 
Return value 
See also 



Gets character from stream. 

int getc (FILE * stream) ; 
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getc is a macro that returns the next character on the given input stream and 
increments the stream's file pointer to point to the next character. 

On success, getc returns the character read, after converting it to an int 
without sign extension. On end-of-file or error, it returns EOF. 

fgetc, getch, getchar, getche, gets, putc, putchar, ungetc 



getch 



conio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Gets character from keyboard, does not echo to screen. 

int getch (void) ; 
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getch reads a single character directly from the keyboard, without echoing 
to the screen. 

This function should not be used in PM applications. 

getch returns the character read from the keyboard. 

cgets, cscanf, fgetc, getc, getchar, getche, getpass, kbhit, putch, ungetch 
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getchar 



getchar 

Function 
Syntax 



Remarks 
Return value 
See also 

getche 



stdio.h 



Gets character from stdin. 

int getchar (void) ; 
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getchar is a macro that returns the next character on the named input stream 
stdin. It is defined to be getc(stdin). 

On success, getchar returns the character read, after converting it to an int 
without sign extension. On end-of-file or error, it returns EOF. 

fgetc, j getchar, freopen, getc, getch, getche, gets, putc, putchar, scanf, ungetc 



conio.h 



Function 
Syntax 



Remarks 

Return value 
See also 

getcurdir 



Gets character from the keyboard, echoes to screen. 

int getche (void) ; 
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getche reads a single character from the keyboard and echoes it to the 
current text window. 

This function should not be used in PM applications. 

getche returns the character read from the keyboard. 

cgets, cscanf, fgetc, getc, getch, getchar, kbhit, putch, ungetch 



dir.h 



Function 
Syntax 



Gets current directory for specified drive. 

int getcurdir(int drive, char *directory) ; 
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Remarks 



Return value 
See also 

getcwd 



getcurdir gets the name of the current working directory for the drive 
indicated by drive, drive specifies a drive number (0 for default, 1 for A, and 
so on), directory points to an area of memory of length MAXDIR where the 
null-terminated directory name will be placed. The name does not contain 
the drive specification and does not begin with a backslash. 

getcurdir returns on success or -1 in the event of error. 

chdir, getcwd, getdisk, mkdir, rmdir 



dir.h 




Function 
Syntax 



Remarks 



Return value 



Gets current working directory. 

char *getcwd(char *buf, int buflen) ; 
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getcwd gets the full path name (including the drive) of the current working 
directory, up to buflen bytes long and stores it in buf. If the full path name 
length (including the null character) is longer than buflen bytes, an error 
occurs. 

If buf is NULL, a buffer buflen bytes long is allocated for you with malloc. 
You can later free the allocated buffer by passing the return value of getcwd 
to the function free. 

getcwd returns the following values: 

b If buf 'is not NULL on input, getcwd returns buf on success, NULL on 
error. 

b If buf is NULL on input, getcwd returns a pointer to the allocated buffer. 

In the event of an error return, the global variable errno is set to one of the 
following values: 



See also 



ENODEV No such device 

ENOMEM Not enough memory to allocate a buffer {buf is NULL) 

ERANGE Directory name longer than buflen {buf is not NULL) 

chdir, getcurdir, _getdcwd, getdisk, mkdir, rmdir 
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_getdcwd 



getdate 



See _dos_getdate on page 45. 



_getdcwd 



direct.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Gets current directory for specified drive. 

char * _getdcwd(int drive, char *buffer, int buflen) 
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_getdcwd gets the full path name of the working directory of the specified 
drive (including the drive name), up to buflen bytes long, and stores it in 
buffer. If the full path name length (including the null character) is longer 
than buflen, an error occurs. The drive is for the default drive, 1=A, 2=B, 
and so on. 

If buffer is NULL, _getdcwd allocates a buffer at least buflen bytes long. You 
can later free the allocated buffer by passing the _getdcwd return value to 
the free function. 

If successful, _getdcwd returns a pointer to the buffer containing the current 
directory for the specified drive. Otherwise it returns NULL, and sets the 
global variable errno to one of the following values: 

ENOMEM Not enough memory to allocate a buffer {buffer is NULL) 
ERANGE Directory name longer than buflen {buffer is not NULL) 

chdir, getcwd, _getdrive, mkdir, rmdir 



getdfree 



dos.h 



Function 
Syntax 



Remarks 



Gets disk free space. 

void getdfree (unsigned char drive, struct dfree *dtable) ; 
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getdfree accepts a drive specifier in drive (0 for default, 1 for A, and so on) 
and fills the dfree structure pointed to by dtable with disk attributes. 
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getdfree 



The dfree structure is defined as follows: 



struct dfree { 

unsigned df_avail; 

unsigned df_total; 

unsigned df_bsec; 

unsigned 'df_sclus; 
}; 



/* available clusters */ 

/* total clusters */ 

/* bytes per sector */ 

/* sectors per cluster */ 



Return value getdfree returns no value. In the event of an error, df_sclus in the dfree 

structure is set to (unsigned) -1. 

getdisk, setdisk dir.h 




Function 
Syntax 



Remarks 



Return value 
See also 



Gets or sets the current drive number. 

int getdisk (void) ; 

int setdisk(int drive); 
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getdisk gets the current drive number. It returns an integer: for A, 1 for B, 2 
for C, and so on. setdisk sets the current drive to the one associated with 
drive: for A, 1 for B, 2 for C, and so on. 

Only the current process is affected. 

getdisk returns the current drive number, setdisk returns the total number of 
drives available. 

getcurdir, getcwd 



_getdrive 



direct.h 



Function 
Syntax 



Remarks 



Gets current drive number. 

int _getdrive(void) ; 
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_getdrive gets the current drive number. It returns an integer: 1 for A, 2 for 
B, 3 for C, and so on. 
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_getdrive 



Return value 
See also 



_getdrive returns the current drive number. 
_dos_getdrive, _dos_setdrive, _getdcwd 



getenv 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Gets a string from environment. 

char *getenv(const char *name) ; 
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getenv returns the value of a specified variable. On DOS and OS/2, name 
must be uppercase. On other systems, name can be either uppercase or low- 
ercase, name must not include the equal sign (=). If the specified 
environment variable does not exist, getenv returns a NULL pointer. 

To delete the variable from the environment, use getenv ( "name=" ) . 

Environment entries must not be changed directly. If you want to change 
an environment value, you must use putenv. 

On success, getenv returns the value associated with name. If the specified 
name is not defined in the environment, getenv returns a NULL pointer. 

_environ (global variable), putenv 



getftime, setftime 



io.h 



Function 
Syntax 



Remarks 



Gets and sets the file date and time. 

int getftime (int handle, struct ftime *ftimep) ; 
int setftime (int handle, struct ftime *ftimep) ; 
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getftime retrieves the file time and date for the disk file associated with the 
open handle. The ftime structure pointed to by ftimep is filled in with the 
file's time and date. 

setftime sets the file date and time of the disk file associated with the open 
handle to the date and time in the ftime structure pointed to by ftimep. The 
file must not be written to after the setftime call or the changed information 
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will be lost. The file must be open for writing; an EACCES error will occur 
if the file is open for read-only access. 

The ftime structure is defined as follows: 



struct ftime { 




unsigned ft_tsec: 5; 


/* two seconds */ 


unsigned ftjnin: 6; 


/* minutes */ 


unsigned ft_hour: 5; 


/* hours */ 


unsigned ft_day: 5; 


/* days */ 


unsigned ft_month: 4; 


/* months */ 


unsigned ft_year: 7; 
}; 


/* year - 1980*/ 



I 



Return value getftime and setftime return on success. 

In the event of an error return, -1 is returned and the global variable errno 
is set to one of the following values: 



See also 



EACCES 
EBADF 

EINVFNC 

fflush, open 



Permission denied 
Bad file number 
Invalid function number 



getpass 



conio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Reads a password. 

char *getpass (const char *prompt); 
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getpass reads a password from the system console, after prompting with the 
null-terminated string prompt and disabling the echo. A pointer is returned 
to a null-terminated string of up to eight characters (not counting the null 
character). 

This function should not be used in PM applications. 

The return value is a pointer to a static string, which is overwritten with 
each call. 

getch 
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getpid 



getpid 

Function 
Syntax 



Remarks 
Return value 



process.h 



Gets the process ID of a program. 

unsigned getpid (void) 
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This function returns the current process ID — an integer that uniquely 
identifies the process. 

getpid returns the identification number of the current process. 



gets 



stdio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Gets a string from stdin. 

char *gets(char *s) ; 
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gets collects a string of characters terminated by a new line from the 
standard input stream stdin and puts it into s. The new line is replaced by a 
null character ('\0') in s. 

gets allows input strings to contain certain whitespace characters (spaces, 
tabs), gets returns when it encounters a new line; everything up to the new 
line is copied into s. 

This function should not be used in PM applications. 

On success, gets returns the string argument s; it returns NULL on end-of- 
file or error. 

cgets, ferror , fgets, fopen, fputs, fread, freopen, getc, puts, scanf 



gettext 



conio.h 



Function 
Syntax 



Copies text from text mode screen to memory. 

int gettext (int left, int top, int right, int bottom, void *destin) 
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Remarks 



Return value 
See also 
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gettext stores the contents of an onscreen text rectangle defined by left, top, 
right, and bottom into the area of memory pointed to by destin. 

All coordinates are absolute screen coordinates, not window-relative. The 
upper left corner is (1,1). 

gettext reads the contents of the rectangle into memory sequentially from 
left to right and top to bottom. 

Each position onscreen takes 2 bytes of memory: The first byte is the 
character in the cell, and the second is the cell's video attribute. The space 
required for a rectangle w columns wide by h rows high is defined as 

bytes = (h rows) x (w columns) x 2 

This function should not be used in PM applications. 

gettext returns 1 if the operation succeeds. It returns if it fails (for example, 
if you gave coordinates outside the range of the current screen mode). 

movetext, puttext 




gettextinfo 



conio.h 



Function 
Syntax 



Gets text mode video information. 

void gettextinfo (struct text_info *r) ; 



Remarks 
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gettextinfo fills in the textjnfo structure pointed to by r with the current text 
video information. 

The textjnfo structure is defined in conio.h as follows: 



struct text_info { 

unsigned char winleft; / i 

unsigned char wintop; /* 

unsigned char winright; /* 

unsigned char winbottom; /* 

unsigned char attribute; /* 

unsigned char normattr; /* 

unsigned char currmode; /* 
unsigned char screenheight; I* 



left window coordinate */ 

top window coordinate *l 

right window coordinate */ 

bottom window coordinate */ 

text attribute */ 

normal attribute */ 

BW40, BW80, C40, C80, or C4350 */ 

text screen's height */ 
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gettextinfo 



unsigned char screenwidth; 
unsigned char curx; 
unsigned char cury; 



/* text screen's width */ 

/* x-coordinate in current window */ 

/* y-coordinate in current window */ 



b^- This function should not be used in PM applications. 

Return value gettextinfo returns nothing; the results are returned in the structure pointed 

to by r. 

See also textattr, textbackground, textcolor, textmode, wherex, wherey, window 



gettime, settime 



dos.h 



Function 
Syntax 



Remarks 



gettime 
settime 



Return value 
See also 



Gets and sets the system time. 

void gettime (struct time *timep) ; 
void settime (struct time *timep); 
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gettime fills in the time structure pointed to by timep with the system's 
current time. 

settime sets the system time to the values in the time structure pointed to by 
timep. 

The time structure is defined as follows: 



struct time { 

unsigned char ti_min; 

unsigned char ti_hour; 

unsigned char ti_hund; 

unsigned -char ti_sec; 
}; 



/* minutes */ 

/* hours */ 

/* hundredths of seconds */ 

/* seconds */ 



None. 

_dos_gettime, _dos_settime, getdate, setdate, stime, time 



getverify 



dos.h 



Function 
Syntax 



Returns the state of the operating system verify flag. 

int getverify (void) ; 
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getverify 



Remarks 



Return value 
See also 
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getverify gets the current state of the verify flag. 

The verify flag controls output to the disk. When verify is off, writes are not 
verified; when verify is on, all disk writes are verified to ensure proper 
writing of the data. 

getverify returns the current state of the verify flag, either (off) or 1 (on). 

setverify 




getw 



stdio.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Gets integer from stream. 

int getw(FILE * stream) ; 
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getw returns the next integer in the named input stream. It assumes no 
special alignment in the file. 

getw should not be used when the stream is opened in text mode. 

getw returns the next integer on the input stream. On end-of-file or error, 
getw returns EOF. Because EOF is a legitimate value for getw to return, feof 
or j "error should be used to detect end-of-file or error. 

putw 



gmtime 



time.h 



Function 
Syntax 



Remarks 



Converts date and time to Greenwich mean time (GMT). 

struct tm *gmtime(const time_t *timer); 
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■ 


■ 


■ 



gmtime accepts the address of a value returned by time and returns a 
pointer to the structure of type tm containing the time elements, gmtime 
converts directly to GMT. 
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gmtime 



The global long variable Jtimezone should be set to the difference in seconds 
between GMT and local standard time (in PST, Jimezone is 8x60x60). The 
global variable _daylight should be set to nonzero only if the standard U.S. 
daylight saving time conversion should be applied. 

This is the t m structure declaration from the time.h header file: 



struct 


tm { 




int 


tm_sec ; 


/ 


int 


tm_min; 


/ 


int 


tm_hour; 


/ 


int 


tmjnday ; 


/ 


int 


tm_mon; 


/ 


int 


tm_year; 


/ 


int 


tm_wday; 


/ 


int 


tm_yday ; 


/ 


int 


tm_isdst; 


/ 



Seconds */ 

Minutes */ 

Hour (0 - 23) V 

Day of month (1 - 31) */ 

Month (0 - 11) */ 

Year (calendar year minus 1900) */ 

Weekday (0 - 6; Sunday is 0) */ 

Day of year (0 -365) */ 

Nonzero if daylight saving time is in effect. */ 



These quantities give the time on a 24-hour clock, day of month (1 to 31), 
month (0 to 11), weekday (Sunday equals 0), year - 1900, day of year (0 to 
365), and a flag that is nonzero if daylight saving time is in effect. 

Return value gmtime returns a pointer to the structure containing the time elements. This 

structure is a static that is overwritten with each call. 

See also asctime, dime, f time, localtime, stime, time, tzset 



gotoxy 



conio.h 



Function 
Syntax 



Remarks 



Positions cursor in text window. 

void gotoxy(int x, int y) ; 
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■ 


■ 






■ 



Return value 



gotoxy moves the cursor to the given position in the current text window. If 
the coordinates are in any way invalid, the call to gotoxy is ignored. An 
example of this is a call to gotoxy '(40, 30), when (35,25) is the bottom right 
position in the window. 

Neither argument to gotoxy can be zero. 

This function should not be used in PM applications. 

None. 
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gotoxy 



See also 

Jieapadd 



wherex, wherey, window 



malloc.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Add a block to the heap. 

int Jieapadd (void *block, size_t size); 
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ANSI C++ 
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■ 



This function adds a new block of memory to the heap. The block must not 
have been previously allocated from the heap. Jieapadd is typically used to 
add large static data areas to the heap. 

Jieapadd returns if it is successful, and -1 if it is unsuccessful. 

free, malloc 




heapcheck 



alloc.h 



Function 
Syntax 



Remarks 



Return value 



Checks and verifies the heap. 

int heapcheck (void) ; 
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■ 



heapcheck walks through the heap and examines each block, checking its 
pointers, size, and other critical attributes. 

The return value is less than for an error and greater than for success. 
The return values and their meaning are as follows: 

_HEAPCORRUPT Heap has been corrupted 
_HEAPEMPTY No heap 

_HEAPOK Heap is verified 



heapcheckfree 



alloc.h 



Function 



Checks the free blocks on the heap for a constant value. 
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heapcheckfree 



Syntax 



Return value 



int heapcheckfree (unsigned int fillvalue); 
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■ 



The return value is less then for an error and greater than for success. 
The return values and their meaning are as follows: 



_BAD VALUE A value other than the fill value was found 

_HEAPCORRUPT Heap has been corrupted 

JHKAPEMPTY No heap 

_HEAPOK Heap is accurate 



heapchecknode 



alloc.h 



Function 
Syntax 



Remarks 



Return value 



Checks and verifies a single node on the heap. 

int heapchecknode (void *node) ; 
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■ 






■ 



If a node has been freed and heapchecknode is called with a pointer to the 
freed block, heapchecknode can return _BADNODE rather than the expected 
_FREEENTRY. This is because adjacent free blocks on the heap are merged, 
and the block in question no longer exists. 

One of the following values: 



_BADNODE Node could not be found 

_FREEENTRY Node is a free block 

_HEAPCORRUPT Heap has been corrupted 

_HEAPEMPTY No heap 

USEDENTRY Node is a used block 



Jieapchk 



malloc.h 



Function 
Syntax 



Checks and verifies the heap. 

int _heapchk(void) ; 
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Jieapchk 



Remarks 
Return value 



See also 



DOS 
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Win 16 


Win 32 
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■ 



Jieapchk walks through the heap and examines each block, checking its 
pointers, size, and other critical attributes. 

One of the following values: 

_HEAPBADNODE A corrupted heap block has been found 

JiEAPEMPTY No heap exists 

JHEAPOK The heap appears to be uncorrupted 

Jieapset, _rtl_heapzvalk 




heapfillfree 



alloc.h 



Function 
Syntax 



Return value 



Fills the free blocks on the heap with a constant value. 

int heapfillfree (unsigned int fillvalue) ; 
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■ 



One of the following values: 

JHEAPCORRUPT Heap has been corrupted 
_HEAPEMPTY No heap 

_HEAPOK Heap is accurate 



Jieapmin 



malloc.h 



Function 
Syntax 



Remarks 



Release unused heap areas. 

int Jieapmin (void) ; 
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■ 
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■ 



The Jieapmin function returns unused areas of the heap to the operating 
system. This allows blocks that have been allocated and then freed to be 
used by other processes. Due to fragmentation of the heap, Jieapmin might 
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_heapmin 



Return value 
See also 



not always be able to return unused memory to the operating system; this 
is not an error. 

Jieapmin returns if it is successful, or -1 if an error occurs. 

free, malloc 



Jieapset 



malloc.h 



Function 
Syntax 



Remarks 



Return value 



Fills the free blocks on the heap with a constant value. 

int Jieapset (unsigned int fil'lvalue) ; 
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■ 






■ 



Jieapset checks the heap for consistency using the same methods as 
Jieapchk. It then fills each free block in the heap with the value contained in 
the least significant byte oifillvalue. This function can be used to find heap- 
related problems. It does not guarantee that subsequently allocated blocks 
will be filled with the specified value. 

One of the following values: 



See also 



_HEAPOK The heap appears to be uncorrupted 

_HEAPEMPTY No heap exists 

_HEAPBADNODE A corrupted heap block has been found 

Jieapchk, jtljieapwalk 



heapwalk 



alloc.h 



Function 
Syntax 



Remarks 



heapwalk is used to "walk" through the heap, node by node. 

int heapwalk (struct heapinfo *hi); 
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heapwalk assumes the heap is correct. Use heapcheck to verify the heap before 
using heapwalk. _HEAPOK is returned with the last block on the heap. 
_HEAPEND will be returned on the next call to heapwalk. 

heapwalk receives a pointer to a structure of type heapinfo (declared in 
alloc.h). For the first call to heapwalk, set the hi.ptr field to null, heapwalk 
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heapwalk 



Return value 



returns with hi.ptr containing the address of the first block, hi.size holds 
the size of the block in bytes. hi.in_use is a flag that's set if the block is 
currently in use. 

One of the following values: 



See also 



Jieapwalk 



_HEAPEMPTY 

_HEAPEND 

_HEAPOK 

_rtl_heapwalk 



No heap 

End of the heap has been reached 

Heapinfo block contains valid data 



malloc.h 




Remarks 



Obsolete function. See _rtl Jieapwalk. 



highvideo 



conio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Selects high-intensity characters. 

void highvideo (void) ; 
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OS/2 


■ 
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■ 



highvideo selects high-intensity characters by setting the high-intensity bit of 
the currently selected foreground color. 

This function does not affect any characters currently onscreen, but does 
affect those displayed by functions (such as cprintf) that perform direct 
video, text mode output after highvideo is called. 

This function should not be used in PM applications. 

None. 

cprintf, cputs, gettextinfo, lowvideo, normvideo, textattr, textcolor 



hypot, hypotl 



math.h 



Function 
Syntax 



Calculates hypotenuse of a right triangle. 

double hypot (double x, double y) ; 

long double hypotl (long double x, long double y) ; 
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hypot, hypotl 



Remarks 



hypot 
hypotl 



Return value 
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■ 
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hypot calculates the value z where 

z 2 = x 2 + y 2 and z >= 

This is equivalent to the length of the hypotenuse of a right triangle, if the 
lengths of the two sides are x and y. 

hypotl is the long double version; it takes long double arguments and 
returns a long double result. 

On success, these functions return z, a double (hypot) or a long double 
(hypotl). On error (such as an overflow), they set the global variable errno to 

ERANGE Result out of range 

and return the value HUGE_VAL (hypot) or _LHUGE_VAL (hypotl). Error 
handling for these routines can be modified through the functions jnatherr 
and matherrl. 



insline 



conio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Inserts a blank line in the text window. 

void insline (void) ; 
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insline inserts an empty line in the text window at the cursor position using 
the current text background color. All lines below the empty one move 
down one line, and the bottom line scrolls off the bottom of the window. 

This function should not be used in PM applications. 

None. 

clreol, delline, window 



isalnum 



ctype.h 



Function 



Tests for an alphanumeric character. 
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isalnum 



Syntax 



Remarks 



int isalnum (int c) ; 



Return value 



isalpha 
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■ 
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isalnum is a macro that classifies ASCII-coded integer values by table 
lookup. The macro is affected by the current locale's LC_CTYPE category. 
For the default C locale, c is a letter (A to Z or a to z) or a digit (0 to 9). 

You can make this macro available as a function by undefining (#undef) it. 

It is a predicate returning nonzero for true and for false, isalnum returns 
nonzero if c is a letter or a digit. 



ctype.h 




Function 
Syntax 



Remarks 



Return value 



Classifies an alphabetical character. 

int isalpha (int c) ; 
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■ 


■ 



isalpha is a macro that classifies ASCII-coded integer values by table lookup. 
The macro is affected by the current locale's LC_CTYPE category. For the 
default C locale, c is a letter (A to Z or a to z). 

You can make this macro available as a function by undefining (#undef) it. 

isalpha returns nonzero if c is a letter. 



isascn 



ctype.h 



Function 
Syntax 



Remarks 



Character classification macro. 

int isascii(int c) ; 
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■ 



isascii is a macro that classifies ASCII-coded integer values by table lookup. 
It is a predicate returning nonzero for true and for false. 

isascii is defined on all integer values. 
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isascn 



Return value isascii returns nonzero if the low order byte of c is in the range to 127 

(0x00-0x7F). 



isatty 



io.h 



Function 
Syntax 



Remarks 



Return value 



Checks for device type. 

int isatty (int handle); 
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■ 



isatty determines whether handle is associated with any one of the following 
character devices: 

■ A terminal 

■ A console 

■ A printer 

■ A serial port 

If the device is one of the four character devices listed above, isatty returns 
a nonzero integer. If it is not such a device, isatty returns 0. 



iscntrl 



ctype.h 



Function 
Syntax 



Remarks 



Return value 



Tests for a control character. 

int iscntrl (int c) ; 
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iscntrl is a macro that classifies ASCII-coded integer values by table lookup. 
The macro is affected by the current locale's LC_CTYPE category. For the 
default C locale, c is a delete character or control character (0x7F or 0x00 to 
OxlF). 

You can make this macro available as a function by undefining (#undef) it. 

iscntrl returns nonzero if c is a delete character or ordinary control 
character. 
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isdigit 



isdigit 

Function 
Syntax 



Remarks 



Return value 



ctype.h 



Tests for decimal-digit character. 

int isdigit (int c) ; 
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isdigit is a macro that classifies ASCII-coded integer values by table lookup. 
The macro is affected by the current locale's LC_CTYPE category. For the 
default C locale, c is a digit (0 to 9). 

You can make this macro available as a function by undefining (#undef) it. 

isdigit returns nonzero if c is a digit. 




isgraph 



ctype.h 



Function 
Syntax 



Remarks 



Return value 



Tests for printing character. 

int isgraph (int c) ; 
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isgraph is a macro that classifies ASCII-coded integer values by table 
lookup. The macro is affected by the current locale's LC_CTYPE category. 
For the default C locale, c is a printing character except blank space (' '). 

You can make this macro available as a function by undefining (#undef) it. 

isgraph returns nonzero if c is a printing character. 



islower 



ctype.h 



Function 
Syntax 



Tests for lowercase character. 

int islower (int c) ; 
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■ 


■ 
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islower 



Remarks islower is a macro that classifies ASCII-coded integer values by table 

lookup. The macro is affected by the current locale's LC_CTYPE category. 
For the default C locale, c is a lowercase letter (a to z). 

You can make this macro available as a function by undefining (#undef) it. 

Return value islower returns nonzero if c is a lowercase letter. 



isprint 



ctype.h 



Function 
Syntax 



Remarks 



Return value 



Tests for printing character. 

int isprint (int c) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



isprint is a macro that classifies ASCII-coded integer values by table lookup. 
The macro is affected by the current locale's LC_CTYPE category. For the 
default C locale, c is a printing character including the blank space (' '). 

You can make this macro available as a function by undefining (#undef) it. 

isprint returns nonzero if c is a printing character. 



ispunct 



ctype.h 



Function 
Syntax 



Remarks 



Return value 



Tests for punctuation character. 

int ispunct (int c) ; 
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ispunct is a macro that classifies ASCII-coded integer values by table 
lookup. The macro is affected by the current locale's LC_CTYPE category. 
For the default C locale, c is any printing character that is neither an alpha- 
numeric nor a blank space (' '). 

You can make this macro available as a function by undefining (#undef) it. 

ispunct returns nonzero if c is a punctuation character. 
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isspace 



isspace 

Function 
Syntax 



Remarks 



Return value 



ctype.h 



Tests for space character. 

int isspace (int c) ; 
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isspace is a macro that classifies ASCII-coded integer values by table lookup. 
The macro is affected by the current locale's LC_CTYPE category. 

You can make this macro available as a function by undefining (#undef) it. 

isspace returns nonzero if c is a space, tab, carriage return, new line, vertical 
tab, formfeed (0x09 to OxOD, 0x20), or any other locale-defined space 
character. 




isupper 



ctype.h 



Function 
Syntax 



Remarks 



Return value 



Tests for uppercase character. 

int isupper (int c) ; 
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isupper is a macro that classifies ASCII-coded integer values by table 
lookup. The macro is affected by the current locale's LC_CTYPE category. 
For the default C locale, c is an uppercase letter (A to Z). 

You can make this macro available as a function by undefining (#undef) it. 

isupper returns nonzero if c is an uppercase letter. 



isxdigit 



ctype.h 



Function 
Syntax 



Tests for hexadecimal character. 

int isxdigit (int c) ; 
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isxdigit 



Remarks 



Return value 
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isxdigit is a macro that classifies ASCII-coded integer values by table 
lookup. The macro is affected by the current locale's LC_CTYPE category. 

You can make this macro available as a function by undefining (#undef) it. 

isxdigit returns nonzero if c is a hexadecimal digit (0 to 9, A to F, a to f) or 
any other hexadecimal digit defined by the locale. 



itoa 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Converts an integer to a string. 

char *itoa(int value, char *string, int radix); 
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itoa converts value to a null-terminated string and stores the result in string. 
With itoa, value is an integer. 

radix specifies the base to be used in converting value; it must be between 2 
and 36, inclusive. If value is negative and radix is 10, the first character of 
string is the minus sign (-). 

The space allocated for string must be large enough to hold the returned 
string, including the terminating null character (\0). itoa can return up to 33 
bytes. 

itoa returns a pointer to string. 

Itoa, ultoa 



kbhit 



conio.h 



Function 
Syntax 



Checks for currently available keystrokes. 

int kbhit (void) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


' 
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kbhit 



Remarks 

Return value 
See also 



kbhit checks to see if a keystroke is currently available. Any available 
keystrokes can be retrieved with getch or getche. 

This function should not be used in PM applications. 

If a keystroke is available, kbhit returns a nonzero value. Otherwise, it 
returns 0. 

getch, getche 



labs 



math.h 



Function 
Syntax 



Remarks 
Return value 
See also 



Gives long absolute value. 

long labs (long int x) ; 
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labs computes the absolute value of the parameter x. 
labs returns the absolute value of x. 

abs, cabs, fobs 



Idexp, Idexpl 



math.h 



Function 
Syntax 



Idexp 
Idexpl 



Remarks 



Return value 



See also 



Calculates x x 2 ex P. 

double Idexp (double x, int exp); 

long double Idexpl (long double x, int exp); 
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Idexp calculates the double value x x 2 ex ?. 

expl is the long double version; it takes a long double argument for x and 
returns a long double result. 

On success, Idexp (or Idexpl) returns the value it calculated, x x 2 ex P. Error 
handling for these routines can be modified through the functions jnatherr 
and jnatherrl. 

exp, fr exp, modf 
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Idiv 



Idiv 

Function 
Syntax 



Remarks 



Return value 
See also 



stdlib.h 



Divides two longs, returning quotient and remainder. 

ldiv_t ldivflong int numer, long int denom) ; 
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Idiv divides two longs and returns both the quotient and the remainder as 
an IdivJ type, numer and denom are the numerator and denominator, 
respectively. The Idivjt type is a structure of longs defined in stdlib.h as 
follows: 



typedef struct { 
long int quot; 
long int rem; 
} ldiv_t; 



/* quotient */ 
/* remainder */ 



Idiv returns a structure whose elements are quot (the quotient) and rem (the 
remainder). 

div 



Ifind 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 



Performs a linear search. 

void *lfind(const void *key, const void *base, size_t *num, size_t width, 
int (JJSERENTRY *fcmp) (const void *, const void *)); 
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Ifind makes a linear search for the value of key in an array of sequential 
records. It uses a user-defined comparison routine fcmp. The fcmp function 
must be used with the _USERENTRY calling convention. 

The array is described as having *num records that are width bytes wide, 
and begins at the memory location pointed to by base. 

Ifind returns the address of the first entry in the table that matches the 
search key. If no match is found, Ifind returns NULL. The comparison 
routine must return if *eleml == *e\eml, and nonzero otherwise (eleml and 
eleml are its two parameters). 
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Ifind 



See also 



bsearch, Isearch, qsort 



localeconv 



locale.h 



Queries the locale for numeric format. 

struct lconv *localeconv(void) ; 
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Function 
Syntax 



Remarks This function provides information about the monetary and other numeric 

formats for the current locale. The information is stored in a struct lconv 
type. The structure can only be modified by the setlocale. Subsequent calls to 
localeconv will update the lconv structure. 

The lconv structure is defined in locale.h. It contains the following fields: 

Table 2.1 : Locale monetary and numeric settings 

Field Application 




char *decimal_point, 
char *thousands_sep; 

char *grouping; 

char *int_curr_symbol; 

char *currency_symbol; 
char *mon_decimal_point; 
char *mon_thousands_sep; 
char *mon_grouping; 
char *positive_sign; 
char *negative_sign; 
char intjracjtigits; 

char frac_digits; 

char p_cs_precedes; 



Decimal point used in nonmonetary formats. This can never be an empty string. 

Separator used to group digits to the left of the decimal point. Not used with monetary 
quantities. 

Size of each group of digits. Not used with monetary quantities. See the value listing table 
below. 

International monetary symbol in the current locale. The symbol format is specified in the ISO 
4217 Codes for the Representation of Currency and Funds. 

Local monetary symbol for the current locale. 

Decimal point used to format monetary quantities. 

Separator used to group digits to the left of the decimal point for monetary quantities. 

Size of each group of digits used in monetary quantities. See the value listing table below. 

String indicating nonnegative monetary quantities. 

String indicating negative monetary quantities. 

Number of digits after the decimal point that are to be displayed in an internationally formatted 
monetary quantity. 

Number of digits after the decimal point that are to be displayed in a formatted monetary 
quantity. 

Set to 1 if currency_symbol precedes a nonnegative formatted monetary quantity. If 
currency_symbol is after the quantity, it is set to 0. 
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localeconv 



Table 2.1: Locale monetary and numeric settings (continued) 



char p_sep_by_space; 

char n_cs_precedes; 

char n_sep_by_space; 

char p_sign_posn; 
char n_sign_posn; 



Set to 1 if currency_symbol is to be separated from the nonnegative formatted monetary 
quantity by a space. Set to if there is no space separation. 

Set to 1 if currency_symbol precedes a negative formatted monetary quantity. If 
currency_symbol\s after the quantity, set to 0. 

Set to 1 if currency_symbol is to be separated from the negative formatted monetary quantity 
by a space. Set to if there is no space separation. 

Indicate where to position the positive sign in a nonnegative formatted monetary quantity. 

Indicate where to position the positive sign in a negative formatted monetary quantity. 



Any of the above strings (except decimal jpoint) that is empty "" is not 
supported in the current locale. The nonstring char elements are nonnega- 
tive numbers. Any nonstring char element that is set to CHAR_MAX 
indicates that the element is not supported in the current locale. 

The grouping and mon_grouping elements are set and interpreted as follows: 



Value 



Meaning 



CHAR_MAX 


any other integer 



No further grouping is to be performed. 

The previous element is to be used repeatedly for the remainder 
of the digits. 

Indicates how many digits make up the current group. The next 
element is read to determine the size of the next group of digits 
before the current group. 



The p_sign_posn and n_sign_posn elements are set and interpreted as 
follows: 



Value 



Meaning 



Use parentheses to surround the quantity and currency_symbol 

Sign string precedes the quantity and currency_symbol. 

Sign string succeeds the quantity and currency_symbol. 

Sign string immediately precedes the quantity and 
currency_symbol. 

Sign string immediately succeeds the quantity and 
currency_symbol. 
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localeconv 



Return value 



See also 



Returns a pointer to the filled-in structure of type struct Iconv. The values in 
the structure will change whenever setlocale modifies the LC_MONETARY 
or LC_NUMERIC categories. 

setlocale 



localtime 



time.h 



Function 
Syntax 



Remarks 



Return value 



Converts date and time to a structure. 

struct tm *localtime (const time_t *timer) ; 
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■ 


■ 


■ 


■ 


■ 


■ 



localtime accepts the address of a value returned by time and returns a 
pointer to the structure of type tm containing the time elements. It corrects 
for the time zone and possible daylight saving time. 

The global long variable timezone contains the difference in seconds 
between GMT and local standard time (in PST, timezone is 8x60x60). The 
global variable daylight contains nonzero only if the standard U.S. daylight 
saving time conversion should be applied. These values are set by tzset, not 
by the user program directly. 

This is the tm structure declaration from the time.h header file: 

struct tm { 

int tm_sec; 

int tm_min; 

int tm_hour; 

int tm_mday; 

int tm_mon; 

int tm_year; 

int tm_wday; 

int tm_yday; 

int tm_isdst; 
}; 

These quantities give the time on a 24-hour clock, day of month (1 to 31), 
month (0 to 11), weekday (Sunday equals 0), year - 1900, day of year (0 to 
365), and a flag that is nonzero if daylight saving time is in effect. 

localtime returns a pointer to the structure containing the time elements. 
This structure is a static that is overwritten with each call. If the local time 
cannot be represented, localtime returns NULL. 
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localtime 
See also 

lock 



asctime, ctime,ftime, gmtime, stime, time, tzset 



io.h 



Function 
Syntax 



Remarks 
Return value 

See also 

locking 



Sets file-sharing locks. 

int lock (int handle, long offset, long length); 
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lock provides an interface to the operating system file-sharing mechanism. 
A lock can be placed on arbitrary, nonoverlapping regions of any file. 

lock returns on success. On error, lock returns -1 and sets the global 
variable errno to 

EACCES Locking violation 

locking, open, sopen, unlock 



io.h, sys\locking.h 



Function 
Syntax 



Remarks 



Sets or resets file-sharing locks. 

int lockingfint handle, int cmd, long length); 
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locking provides an interface to the operating system file-sharing 
mechanism. The file to be locked or unlocked is the open file specified by 
handle. The region to be locked or unlocked starts at the current file 
position, and is length bytes long. 

Locks can be placed on arbitrary, nonoverlapping regions of any file. A 
program attempting to read or write into a locked region will retry the 
operation three times. If all three retries fail, the call fails with an error. 

The cmd values (defined in sysMocking.h) specify the action to be taken: 
LK_LOCK Lock the region. If the lock is unsuccessful, try once a 

second for 10 seconds before giving up. 

LK_RLCK Same as LKJLOCK, except that on OS/2 other 

processes are allowed shared (read-only) access. 
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locking 



LK_NBLCK Lock the region. If the lock if unsuccessful, give up 
immediately. 

LK_NBRLCK Same as LK_NBLCK, except that on OS/2, other 
processes are allowed shared (read-only) access. 

LK_UNLCK Unlock the region, which must have been previously 
locked. 

Return value On successful operations, locking returns 0. Otherwise, it returns -1, and the 

global variable errno is set to one of the following values: 



See also 



log, logl 



EACCES File already locked or unlocked 

EBADF Bad file number 

EDEADLOCK File cannot be locked after 10 retries {cmd is LK_LOCK 

or LK_RLCK) 
EINVAL Invalid cmd 



_fsopen, lock, open, sopen, unlock 




math.h 



Function 
Syntax 



Remarks 



Return value 



log 
logl 



Calculates the natural logarithm of x. 

double log(double x) ; 

long double logl(long double x); 
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log calculates the natural logarithm of x. 

logl is the long double version; it takes a long double argument and returns 
a long double result. 

This function can be used with bed and complex types. 

On success, log and logl return the value calculated, ln(x). 

If the argument x passed to these functions is real and less than 0, the 
global variable errno is set to 

EDOM Domain error 

If x is 0, the functions return the value negative HUGE_VAL (log) or 
negative _LHUGE_VAL (logl), and set errno to ERANGE. Error handling for 
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log, logl 



See also 



these routines can be modified through the functions _matherr and 
jnatherrl. 

bed, complex, exp, loglO, sqrt 



loglO, Iog10l 



math.h 



Function 
Syntax 



Iog10 
Iog101 



Remarks 



Return value 



See also 



Calculates log io(x). 

double loglO (double x) ; 

long double logl01(long double x) 
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loglO calculates the base 10 logarithm of x. 

loglOl is the long double version; it takes a long double argument and 
returns a long double result. 

This function can be used with bed and complex types. 

On success, loglO (or loglOl) returns the value calculated, log w (x). 

If the argument x passed to these functions is real and less than 0, the 
global variable errno is set to 

EDOM Domain error 

If x is 0, these functions return the value negative HUGE_VAL (loglO) or 
_LHUGE_VAL (loglOl). Error handling for these routines can be modified 
through the functions jnatherr and jnatherrl. 

bed, complex, exp, log 



longjmp 



setjmp.h 



Function 
Syntax 



Performs nonlocal goto. 

void longjmp (jmp_buf jmpb, int retval); 
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ANSI C++ 
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longjmp 



Remarks 



A call to longjmp restores the task state captured by the last call to setjmp 
with the argument jmpb. It then returns in such a way that setjmp appears to 
have returned with the value retval. 

A task state includes: 



Return value 
See also 



d no segment registers are saved 

■ register variables (EBX, EDI, ESI) 

■ stack pointer (ESP) 

■ frame base pointer (EBP) 
a flags are not saved 

A task state is complete enough that setjmp and longjmp can be used to 
implement co-routines. 

setjmp must be called before longjmp. The routine that called setjmp and set 
up jmpb must still be active and cannot have returned before the longjmp is 
called. If this happens, the results are unpredictable. 

longjmp cannot pass the value 0; if is passed in retval, longjmp will 
substitute 1. 

You can not use longjmp to switch between different threads in a 
multithread process. That is, do not jump to a jmpjbuf that was saved by a 
setjmp call in a different thread. 

None. 

setjmp, signal 




lowvideo 



conio.h 



Function 
Syntax 



Remarks 



Selects low-intensity characters. 

void lowvideo (void) ; 
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D 



lowvideo selects low-intensity characters by clearing the high-intensity bit of 
the currently selected foreground color. 

This function does not affect any characters currently onscreen. It affects 
only those characters displayed by functions that perform text mode, direct 
console output after this function is called. 
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lowvideo 



Return value 
See also 



This function should not be used in PM applications. 

None. 

highvideo, normvideo, textattr, textcolor 



Jrotl, Jrotr 



stdlib.h 



Function 
Syntax 



Remarks 
Return value 

See also 



Rotates an unsigned long integer value to the left or right. 

unsigned long _lrotl (unsigned long val, int count); 
unsigned long _lrotr (unsigned long val, int count); 
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Jrotl rotates the given val to the left count bits. Jrotr rotates the given val to 
the right count bits. 

The functions return the rotated integer: 

d Jrotl returns the value of val left-rotated count bits. 
b Jrotr returns the value of val right-rotated count bits. 

_crotr, _crotl, jrotl, jrotr 



Isearch 



stdlib.h 



Function 
Syntax 



Remarks 



Performs a linear search. 

void *lsearch (const void *key, void *base, size_t *num, size_t width, 
int (JJSERENTRY *fcmp) (const void *, const void *)); 
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Isearch. searches a table for information. Because this is a linear search, the 
table entries do not need to be sorted before a call to Isearch. If the item that 
key points to is not in the table, Isearch appends that item to the table. 

■ base points to the base (Oth element) of the search table. 

■ num. points to an integer containing the number of entries in the table. 
n width contains the number of bytes in each entry. 

a key points to the item to be searched for (the search key). 
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Isearch 



Return value 



See also 



Iseek 



The function fcmp must be used with the _USERENTRY calling convention. 

The argument fcmp points to a user-written comparison routine, that 
compares two items and returns a value based on the comparison. 

To search the table, Isearch makes repeated calls to the routine whose 
address is passed in fcmp. 

On each call to the comparison routine, Isearch passes two arguments: key, a 
pointer to the item being searched for, and elem, a pointer to the element of 
base being compared. 

fcmp is free to interpret the search key and the table entries in any way. 

Isearch returns the address of the first entry in the table that matches the 
search key. 

If the search key is not identical to * elem, fcmp returns a nonzero integer. If 
the search key is identical to * 'elem, fcmp returns 0. 

bsearch, Ifind, qsort 



io.h 




Function 
Syntax 



Remarks 



Moves file pointer. 

long lseek(int handle, long offset, int fromwhere) ; 
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Iseek sets the file pointer associated with handle to a new position offset bytes 
beyond the file location given by fromwhere. fromwhere must be one of the 
following symbolic constants (defined in io.h): 



fromwhere 



File location 



SEEK_CUR Current file pointer position 

SEEK_END End-of-file 

SEEK_SET File beginning 



Return value Iseek returns the offset of the pointer's new position measured in bytes from 

the file beginning. Iseek returns -1L on error, and the global variable errno is 
set to one of the following values: 
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Iseek 



See also 



EBADF Bad file handle 

EINVAL Invalid argument 
ESPIPE Illegal seek on device 

On devices incapable of seeking (such as terminals and printers), the return 
value is undefined. 

filelength, f seek, f tell, getc, open, sopen, ungetc, _rtl_write, write 



Itoa 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Converts a long to a string. 

char *ltoa(long value, char *string, int radix); 
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Itoa converts value to a null-terminated string and stores the result in string, 
value is a long integer. 

radix specifies the base to be used in converting value; it must be between 2 
and 36, inclusive. If value is negative and radix is 10, the first character of 
string is the minus sign (-). 

The space allocated for string must be large enough to hold the returned 
string, including the terminating null character (\0). Itoa can return up to 33 
bytes. 

Itoa returns a pointer to string. 

itoa, ultoa 



jnakepath 



stdlib.h 



Function 
Syntax 



Remarks 



Builds a path from component parts. 

void jnakepath (char *path, const char *drive, const char *dir, 
const char *name, const char *ext) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 
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jnakepath makes a path name from its components. The new path name is 

X:\DIR\SUBDIR\NAME.EXT 
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where 



jnakepath 



Return value 
See also 



drive 


= 


X: 


dir 


= 


\DIR\SUBDIR\ 


name 


= 


NAME 


ext 


= 


.EXT 



If drive is empty or NULL, no drive is inserted in the path name. If it is 
missing a trailing colon (:), a colon is inserted in the path name. 

If dir is empty or NULL, no directory is inserted in the path name. If it is 
missing a trailing slash (\ or /), a backslash is inserted in the path name. 

If name is empty or NULL, no file name is inserted in the path name. 

If ext is empty or NULL, no extension is inserted in the path name. If it is 
missing a leading period (.), a period is inserted in the path name. 

jnakepath assumes there is enough space in path for the constructed path 
name. The maximum constructed length is _MAX_PATH. _MAX_PATH is 
defined in stdlib.h. 

jnakepath and jsplitpath are invertible; if you split a given path with 
jsplitpath, then merge the resultant components with jnakepath, you end up 
with path. 

None. 

Jiillpath, jsplitpath 




malloc 



stdlib.h 



Function 
Syntax 



Remarks 



Allocates main memory. 

void *malloc(size_t size); 
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malloc allocates a block of size bytes from the memory heap. It allows a 
program to allocate memory explicitly as it's needed, and in the exact 
amounts needed. 

The heap is used for dynamic allocation of variable-sized blocks of 
memory. Many data structures, for example, trees, and lists, naturally 
employ heap memory allocation. 
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malloc 



Return value 



See also 



On success, malloc returns a pointer to the newly allocated block of 
memory. If not enough space exists for the new block, it returns NULL. The 
contents of the block are left unchanged. If the argument size == 0, malloc 
returns NULL. 

calloc,free, realloc 



matherr, matherrl 



math.h 



Function 
Syntax 



Remarks 



User-modifiable math error handler. 

int jnatherr (struct _exception *e) ; 
int jnatherrl (struct _exceptionl *e) ; 
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jnatherr is called when an error is generated by the math library. 

jnatherrl is the long double version; it is called when an error is generated 
by the long double math functions. 

jnatherr and jnatherrl each serve as a user hook (a function that can be 
customized by the user) that you can replace by writing your own math 
error handling routine. The example shows a user-defined jnatherr 
implementation. 

jnatherr and jnatherrl are useful for trapping domain and range errors 
caused by the math functions. They do not trap floating-point exceptions, 
such as division by zero. See signal for information on trapping such errors. 

You can define your own jnatherr or jnatherrl routine to be a custom error 
handler (such as one that catches and resolves certain types of errors); this 
customized function overrides the default version in the C library. The 
customized jnatherr or jnatherrl should return if it fails to resolve the 
error, or nonzero if the error is resolved. If nonzero is returned, no error 
message is printed and the global variable errno is not changed. 

Here are the _exception and _exceptionl structures (defined in math.h): 

struct _exception { 

int type ; 

char *name; 

double argl, arg2, retval; 
}; 

struct _exceptionl { 
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jnatherr, jnatherrl 



int type ; 

char *name; 

long double argl, arg2, retval; 



}; 



The members of the _exception and _exceptionl structures are shown in the 
following table: 



Member What it is (or represents) 



type The type of mathematical error that occurred; an enum type defined in the typedef 

jnexcep (see definition after this list). 

name A pointer to a null-terminated string holding the name of the math library function 

that resulted in an error. 

argl, . The arguments (passed to the function that name points to) caused the error; 

arg2 if only one argument was passed to the function, it is stored in argl. 

retval The default return value for jnatherr (or _matherrf); you can modify this value. 

The typedef jnexcep, also defined in math.h, enumerates the following 
symbolic constants representing possible mathematical errors: 




Symbolic 
constant 



Mathematical error 



DOMAIN 

SING 

OVERFLOW 

UNDERFLOW 

TLOSS 



Argument was not in domain of function, such as /og(-1 ). 

Argument would result in a singularity, such as pow(0, -2). 

Argument would produce a function result greater than DBL_MAX (or 
LDBL_MAX), such as exp(1000). 

Argument would produce a function result less than DBL_MIN (or 
LDBL_MIN),suchasexp(-1000). 

Argument would produce function result with total loss of significant digits, 
suchass/'n(10e70). 

The macros DBL_MAX, DBL_MIN, LDBL_MAX, and LDBL_MIN are 
defined in float.h. 

The source code to the default jnatherr and jnatherrl is on the Borland C++ 
distribution disks. 

The UNIX-style jnatherr and jnatherrl default behavior (printing a 
message and terminating) is not ANSI compatible. If you want a UNIX- 
style version of these routines, use MATHERR.C and MATHERRL.C 
provided on the Borland C++ distribution disks. 
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jnatherr, jnatherrl 



Return value The default return value for jnatherr and jnatherrl is 1 if the error is 

UNDERFLOW or TLOSS, otherwise, jnatherr and jnatherrl can also 
modify e -> retval, which propagates back to the original caller. 

When jnatherr and jnatherrl return (not able to resolve the error), the 
global variable errno is set to and an error message is printed. 

When jnatherr and jnatherrl return nonzero (able to resolve the error), the 
global variable errno is not set and no messages are printed. 



max 



stdlib.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Returns the larger of two values. 

(type) max (a, b) ; 

template <class T> T max( T tl, T t2 ); // C++ template function 
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The C macro and the C++ template function compare two values and 
return the larger of the two. Both arguments and the routine declaration 
must be of the same type. 

max returns the larger of two values. 

min 



mblen 



stdlib.h 



Function 
Syntax 



Remarks 



Determines the length of a multibyte character. 

int mblen(const char *s, size_t n) ; 
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If s is not null, mblen determines the number of bytes in the multibyte char- 
acter pointed to by s. The maximum number of bytes examined is specified 
by n. 

The behavior of mblen is affected by the setting of LC_CTYPE category of 
the current locale. 
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mblen 



Return value 



See also 



If s is null, mblen returns a nonzero value if multibyte characters have 
state-dependent encodings. Otherwise, mblen returns 0. 

If s is not null, mblen returns if s points to the null character, and -1 if the 
next n bytes do not comprise a valid multibyte character; the number of 
bytes that comprise a valid multibyte character. 

mbstowcs, mbtowc, setlocale 



mbstowcs 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Converts a multibyte string to a wchar_t array. 

size_t mbstowcs (wchar_t *pwcs, const char *s, size_t n) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 


■ 


■ 


■ 



The function converts the multibyte string s into the array pointed to by 
pzvcs. No more than n values are stored in the array. If an invalid multibyte 
sequence is encountered, mbstowcs returns (sizejt) -1. 

The pwcs array will not be terminated with a zero value if mbstowcs 
returns n. 

The behavior of mbstowcs is affected by the setting of LC_CTYPE category 
of the current locale. 

If an invalid multibyte sequence is encountered, mbstowcs returns (size_t) 
-1. Otherwise, the function returns the number of array elements modified, 
not including the terminating code, if any. 

mblen, mbtowc, setlocale 




mbtowc 



stdlib.h 



Function 
Syntax 



Remarks 



Converts a multibyte character to wcharj code. 

int mbtowc (wchar_t *pwc, const char *s, size_t n) ; 
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If s is not null, mbtowc determines the number of bytes that comprise the 
multibyte character pointed to by s. Next, mbtowc determines the value of 
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mbtowc 



Return value 



See also 



the type wchar_t that corresponds to that multibyte character. If there is a 
successful match between wchar_t and the multibyte character, and pwc is 
not null, the wchar_t value is stored in the array pointed to by pwc. At most 
n characters are examined. 

When s points to an invalid multibyte character, -1 is returned. When s 
points to the null character, is returned. Otherwise, mbtowc returns the 
number of bytes that comprise the converted multibyte character. 

The return value never exceeds MB_CUR_MAX or the value of n. 

The behavior of mbtowc is affected by the setting of LC_CTYPE category of 
the current locale. 

mblen, mbstowcs, setlocale 



memccpy 



mem.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Copies a block of n bytes. 

void *memccpy(void *dest, const void *src, int c, size_t n) ; 
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memccpy is available on UNIX System V systems. 

memccpy copies a block of n bytes from src to dest. The copying stops as 
soon as either of the following occurs: 

■ The character c is first copied into dest . 
a n bytes have been copied into dest. 

memccpy returns a pointer to the byte in dest immediately following c, if c 
was copied; otherwise, memccpy returns NULL. 

memcpy, memmove, memset 



memchr 



mem.h 



Function 
Syntax 



Searches n bytes for character c. 

void *memchr( const void *s, int c, size_t n) ; 



/* C only */ 
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memchr 



Remarks 



Return value 



const void *memchr (const void *s, int c, size_t n) ; 
void *memchr (void *s, int c, size_t n) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



// C++ only 
// C++ only 



memchr is available on UNIX System V systems. 

memchr searches the first n bytes of the block pointed to by s for character c. 

On success, memchr returns a pointer to the first occurrence of c in s; 
otherwise, it returns NULL. 

If you are using the intrinsic version of these functions, the case of n=0 will 
return NULL. 



memcmp 



mem.h 



I 



Function 
Syntax 



Remarks 



Return value 



Compares two blocks for a length of exactly n bytes. 

int memcmp (const void *sl, const void *s2, size_t n) ; 



DOS 
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■ 


■ 


■ 


■ 


■ 


■ 


■ 



See also 



memcmp is available on UNIX System V systems. 

memcmp compares the first n bytes of the blocks si and s2 as unsigned 
chars. 

Because it compares bytes as unsigned chars, memcmp returns a value that 
is 

■ < if si is less than s2 
a = if si is the same as s2 
a > if si is greater than s2 

For example, 

memcmp ("\xFF", "\x7F", 1) 

returns a value greater than 0. 

If you are using the intrinsic version of these functions, the case of n=0 will 
return NULL. 

memicmp 
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memcpy 



memcpy 

Function 
Syntax 



Remarks 



Return value 
See also 



mem.h 



Copies a block of n bytes. 

void *memcpy(void *dest, const void *src, size_t n) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


" 


■ 


■ 



memcpy is available on UNIX System V systems. 

memcpy copies a block of n bytes from src to dest. If src and dest overlap, the 
behavior of memcpy is undefined. 

memcpy returns dest. 

memccpy, memmove, memset 



memicmp 



mem.h 



Function 
Syntax 



Compares n bytes of two character arrays, ignoring case. 

int memicmp (const void *sl, const void *s2, size_t n) ; 



DOS 
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Win 16 


Win 32 
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OS/2 


■ 


■ 


■ 


■ 






■ 



Remarks 



Return value 



See also 



memicmp is available on UNIX System V systems. 

memicmp compares the first n bytes of the blocks si and si, ignoring 
character case (upper or lower). 

memicmp returns a value that is 

■ < if si is less than s2 

a = if si is the same as s2 

■ > if s 1 is greater than s2 

memcmp 



memmove 



mem.h 



Function 



Copies a block of n bytes. 
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memmove 



Syntax 

Remarks 

Return value 
See also 



void *memmove(void *dest, const void *src, size_t n) ; 



DOS 
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Win 16 


Win 32 
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ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



memmove copies a block of n bytes from src to dest. Even when the source 
and destination blocks overlap, bytes in the overlapping locations are 
copied correctly. 

memmove returns dest. 

memccpy, memcpy 



memset 



mem.h 



Function 
Syntax 



Remarks 
Return value 
See also 



Sets n bytes of a block of memory to byte c. 

void *memset (void *s, int c, size_t n) ; 



DOS 


UNIX 


Win 16 


Win 32 
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ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



memset sets the first n bytes of the array s to the character c. 
memset returns s. 
memccpy, memcpy 



mm 



stdlib.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Returns the smaller of two values. 

(type) min (a, b) ; 

template <class T> T min( T tl, T t2 ); // C++ template function 



DOS 
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Win 32 
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ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



The C macro and the C++ template function compare two values and 
return the smaller of the two. Both arguments and the routine declaration 
must be of the same type. 

min returns the smaller of two values. 



max 
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mkdir 



mkdir 

Function 
Syntax 



Remarks 



Return value 



dir.h 



Creates a directory. 

int mkdir (const char *path) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 






■ 



mkdir is available on UNIX, though it then takes an additional parameter. 

mkdir creates a new directory from the given path name path. 

mkdir returns the value if the new directory was created. 

A return value of -1 indicates an error, and the global variable errno is set to 
one of the following values: 



See also 



EACCES Permission denied 
ENOENT No such file or directory 

chdir, getcurdir, getcwd, rmdir 



mktemp 



dir.h 



Function 
Syntax 



Remarks 



Return value 



Makes a unique file name. 

char *mktemp(char *template) ; 



DOS 
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OS/2 


■ 


■ 


■ 


■ 






■ 



mktemp replaces the string pointed to by template with a unique file name 
and returns template. 

template should be a null-terminated string with six trailing Xs. These Xs 
are replaced with a unique collection of letters plus a period, so that there 
are two letters, a period, and three suffix letters in the new file name. 

Starting with AA.AAA, the new file name is assigned by looking up the 
name on the disk and avoiding pre-existing names of the same format. 

If template is well-formed, mktemp returns the address of the template string. 
Otherwise, it returns null. 
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mktime 



mktime 

Function 
Syntax 



Remarks 



time.h 



Return value 
See also 



Converts time to calendar format. 

time_t mktime (struct tm *t); 



DOS 
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■ 




■ 


■ 


■ 


■ 


■ 



Converts the time in the structure pointed to by t into a calendar time with 
the same format used by the time function. The original values of the fields 
tm_sec, tmjnin, tmjiour, tmjnday, and tmjnon are not restricted to the 
ranges described in the tm structure. If the fields are not in their proper 
ranges, they are adjusted. Values for fields tmjwday and tm_yday are 
computed after the other fields have been adjusted. If the calendar time 
cannot be represented, mktime returns -1. 

The allowable range of calendar times is Jan 1 1970 00:00:00 to Jan 19 2038 
03:14:07. 

See Remarks. 

localtime, strftime, time 




modf, modfl 



math.h 



Function 
Syntax 



Remarks 



modf 
modfl 



Return value 
See also 



Splits a double or long double into integer and fractional parts. 

double modf (double x, double *ipart); 

long double modfl (long double x, long double *ipart); 



DOS 
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Win 16 
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■ 


■ 


■ 


■ 


■ 


■ 


' 


■ 




■ 


■ 






■ 



mod/breaks the double x into two parts: the integer and the fraction, modf 
stores the integer in ipart and returns the fraction. 

modfl is the long double version; it takes long double arguments and 
returns a long double result. 

modf and modfl return the fractional part of x. 

fmod, Idexp 
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movetext 



movetext 

Function 
Syntax 



Remarks 



Return value 



See also 



conio.h 

Copies text onscreen from one rectangle to another. 

int movetext (int left, int top, int right, int bottom, int destleft, int desttop) ; 



DOS 
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Win 16 
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■ 






■ 



movetext copies the contents of the onscreen rectangle defined by left, top, 
right, and bottom to a new rectangle of the same dimensions. The new 
rectangle's upper left corner is position (destleft, desttop). 

All coordinates are absolute screen coordinates. Rectangles that overlap are 
moved correctly. 

movetext is a text mode function performing direct video output. 

This function should not be used in PM applications. 

movetext returns nonzero if the operation succeeded. If the operation failed 
(for example, if you gave coordinates outside the range of the current 
screen mode), movetext returns 0. 

gettext, puttext 



msize 



malloc.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Returns the size of a heap block. 

size_t _msize(void *block) ; 



DOS 


UNIX 


Win 16 


Win 32 
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" 






" 



jnsize returns the size of the allocated heap block whose address is block. 
The block must have been allocated with malloc, calloc, or realloc. The 
returned size can be larger than the number of bytes originally requested 
when the block was allocated. 

jnsize returns the size of the block in bytes. 

malloc, free, realloc 
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normvideo 



normvideo 



conio.h 



Function 
Syntax 



Remarks 



Return value 
See also 

offsetof 

Function 
Syntax 



Remarks 



Return value 



Selects normal-intensity characters. 



void normvideo (void) ; 



DOS 
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■ 






■ 



normvideo selects normal characters by returning the text attribute 
(foreground and background) to the value it had when the program 
started. 

This function does not affect any characters currently on the screen, only 
those displayed by functions (such as cprintf) performing direct console 
output functions after normvideo is called. 

This function should not be used in PM applications. 

None. 

highvideo, lowvideo, textattr, textcolor 

stddef.h 

Gets the byte offset to a structure member. 

size_t offsetof (struct_type, structjnember) ; 



M 
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ANSI C++ 
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■ 


■ 


■ 


■ 


" 


■ 


- 



offsetof 'is available only as a macro. The argument structjype is a struct 
type, structjnember is any element of the struct that can be accessed 
through the member selection operators or pointers. 

If structjnember is a bit field, the result is undefined. 

See also Chapter 2 in the Programmer's Guide for a discussion of the sizeof 
operator, memory allocation and alignment of structures. 

offsetof returns the number of bytes from the start of the structure to the 
start of the named structure member. 
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_open 



open 



fcntl.h, share.h, dos.h 



Remarks 



Obsolete function. See _rtl_open. 



open 



fcntl.h, io.h 



Function 
Syntax 



Remarks 



These symbolic 

constants are defined 

in fcntl.h. 



Opens a file for reading or writing. 

int open(const char *path, int access [, unsigned mode] ) ; 



DOS 
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Win 16 
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■ 


■ 


■ 


■ 






■ 



open opens the file specified by path, then prepares it for reading and /or 
writing as determined by the value of access. 

To create a file in a particular mode, you can either assign to the global 
variable Jmode or call open with the 0_CREAT and 0_TRUNC options 
ORed with the translation mode desired. For example, the call 

open ( "XMP" , 0_CREAT I 0_TRUNC I 0_BINARY, S_IREAD) 

creates a binary-mode, read-only file named XMP, truncating its length to 
bytes if it already existed. 

For open, access is constructed by bitwise ORing flags from the following 
two lists. Only one flag from the first list can be used (and one must be 
used); the remaining flags can be used in any logical combination. 

List 1 : Read/write flags 

0_RDONLY Open for reading only. 

O.WRONLY Open for writing only. 

0_RDWR Open for reading and writing. 

List 2: Other access flags 

0_NDELAY Not used; for UNIX compatibility. 

0_APPEND If set, the file pointer will be set to the end of the file 

prior to each write. 
0_CREAT If the file exists, this flag has no effect. If the file does 

not exist, the file is created, and the bits of mode are 

used to set the file attribute bits as m-chmod. 
0_TRUNC If the file exists, its length is truncated to 0. The file 

attributes remain unchanged. 
O.EXCL Used only with O.CREAT. If the file already exists, 

an error is returned. 



134 



Borland C++ for OS/2 Library Reference 



open 



0_BINARY Can be given to explicitly open the file in binary 

mode. 
0_TEXT Can be given to explicitly open the file in text mode. 

If neither 0_BINARY nor 0_TEXT is given, the file is opened in the 
translation mode set by the global variable Jmode. 

If the 0_CREAT flag is used in constructing access, you need to supply the 
mode argument to open from the following symbolic constants defined in 
sys\stat.h. 



Return value 



Value of mode 



SJWRITE 

SJREAD 

S_IREAD|S_IWRITE 



Access permission 



Permission to write 
Permission to read 
Permission to read and write 



On successful completion, open returns a nonnegative integer (the file 
handle). The file pointer, which marks the current position in the file, is set 
to the beginning of the file. On error, open returns -1 and the global variable 
errno is set to one of the following values: 



See also 



EACCES Permission denied 

EINVACC Invalid access code 

EMFILE Too many open files 

ENOENT No such file or directory 

chmod, chsize, close, creat, creatnew, creattemp, dup, dup2, fdopen, filelength, 
f open, f reopen, getftime, Iseek, lock, _rtl_open, read, sopen, _rtl_creat, _rtl_write, 
write 



I 



opendir 



dirent.h 



Function 
Syntax 



Remarks 



Opens a directory stream for reading. 

DIR *opendir (char *dirname) ; 



DOS 
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Win 16 


Win 32 
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■ 


■ 


■ 


■ 






■ 



opendir is available on POSIX-compliant UNIX systems. 

The opendir function opens a directory stream for reading. The name of the 
directory to read is dirname. The stream is set to read the first entry in the 
directory. 
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opendir 



Return value 



See also 



A directory stream is represented by the DIR structure, defined in dirent.h. 
This structure contains no user-accessible fields. Multiple directory streams 
can be opened and read simultaneously. Directory entries can be created or 
deleted while a directory stream is being read. 

Use the readdir function to read successive entries from a directory stream. 
Use the closedir function to remove a directory stream when it is no longer 
needed. 

If successful, opendir returns a pointer to a directory stream that can be used 
in calls to readdir, rewinddir, and closedir. If the directory cannot be opened, 
opendir returns NULL and sets the global variable errno to 

ENOENT The directory does not exist 

ENOMEM Not enough memory to allocate a DIR object 

closedir, readdir, rewinddir 



_pclose 



stdio.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Waits for piped command to complete. 

int _pclose(FILE * stream); 



DOS 
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■ 






■ 



This function is not available in Win32s programs. 

jpclose closes a pipe stream created by a previous call to jpopen, and then 
waits for the associated child command to complete. 

If it is successful, _pclose returns the termination status of the child 
command. This is the same value as the termination status returned by 
cwait, except that the high and low order bytes of the low word are 
swapped. If jpclose is unsuccessful, it returns -1. 

jpipe, jpopen 



perror 



stdio.h 



Function 
Syntax 



Prints a system error message. 

void perror (const char *s); 
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perror 



DOS 
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■ 




■ 


■ 


■ 


■ 



Remarks 



perror prints to the stderr stream (normally the console) the system error 
message for the last library routine that set errno. 

First the argument s is printed, then a colon, then the message corre- 
sponding to the current value of the global variable errno, and finally a 
newline. The convention is to pass the file name of the program as the 
argument string. 

The array of error message strings is accessed through the global variable 
_sys_errlist. The global variable errno can be used as an index into the array 
to find the string corresponding to the error number. None of the strings 
include a newline character. 

The global variable _sys_nerr contains the number of entries in the array. 

Refer to errno, _sys_errlist, and _sys_nerr in Chapter 3 for more information. 

The following messages are generated by perror: 



Arg list too big 
Attempted to remove 
current 

directory 
Bad address 
Bad file number 
Block device required 
Broken pipe 
Cross-device link 
Error 

Exec format error 
Executable file in use 
File already exists 
File too large 
Illegal seek 
Inappropriate I/O control 

operation 
Input/output error 
Interrupted function call 
Invalid access code 
Invalid argument 
Invalid data 
Invalid environment 
Invalid format 



Invalid function number 

Invalid memory block 

address 

Is a directory 

Math argument 

Memory arena trashed 

Name too long 

No child processes 

No more files 

No space left on device 

No such device 

No such device or address 

No such file or directory 

No such process 

Not a directory 

Not enough memory 

Not same device 

Operation not permitted 

Path not found 

Permission denied 

Possible deadlock 

Read-only file system 

Resource busy 
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perror 



Return value 
See also 



Resource temporarily 

unavailable 
Result too large 



Too many links 
Too many open files 
Too many open files 



This function should not be used in PM applications. 

None. 

clearerr, eof,freopen, _strerror, strerror 



_pipe 



fcntl.h, io.h 



Function 
Syntax 



Remarks 



Creates a read /write pipe. 

int _pipe(int ^handles, unsigned int size, int mode); 



DOS 
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Win 16 


Win 32 
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■ 






■ 



This function is not available in Win32s programs. 

The jpipe function creates an anonymous pipe that can be used to pass 
information between processes. The pipe is opened for both reading and 
writing. Like a disk file, a pipe can be read from and written to, but it does 
not have a name or permanent storage associated with it; data written to 
and from the pipe exist only in a memory buffer managed by the operating 
system. 

The read handle is returned to handles[0], and the write handle is returned 
to handles[l]. The program can use these handles in subsequent calls to read, 
write, dup, dup2, or close. When all pipe handles are closed, the pipe is 
destroyed. 

The size of the internal pipe buffer is size. A recommended minimum value 
is 512 bytes. 

The translation mode is specified by mode, as follows: 



Return value 



0_BINARY The pipe is opened in binary mode 
0_TEXT The pipe is opened in text mode 

If mode is zero, the translation mode is determined by the external variable 

Jmode. 

On successful completion, _pipe returns and returns the pipe handles to 
handles[0] and handles[l]. Otherwise it returns -1 and sets errno to one of the 
following values: 
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_pipe 



See also 



EMFILE Too many open files 

ENOMEM Out of memory 

_pclose, _popen . 



poly, polyl 



math.h 



Function 
Syntax 



Remarks 



poly 
polyl 



Return value 



Generates a polynomial from arguments. 

double poly (double x, int degree, double coeffs[]); 

long double polyl(long double x, int degree, long double coeffsU); 
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■ 
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poly generates a polynomial in x, of degree degree, with coefficients coeffs[0], 
coeffs[l], ..., coeffsldegree]. For example, if n = 4, the generated polynomial is 

coejfs[4]x 4 + coeffs[3]x 3 + coeffs[2]x 2 + coeffs[l]x + coeffs[0] 

polyl is the long double version; it takes long double arguments and returns 
a long double result. 

poly and polyl return the value of the polynomial as evaluated for the 
given x. 



1 



_popen 



stdio.h 



Function 
Syntax 



Remarks 



Creates a command processor pipe. 

FILE *_popen (const char *command, const char *mode) ; 



DOS 
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Win 16 


Win 32 
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ANSI C++ 


OS/2 
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■ 






■ 



This function is not available in Win32s programs. 

The _popen function creates a pipe to the command processor. The 
command processor is executed asynchronously, and is passed the 
command line in command. The mode string specifies whether the pipe is 
connected to the command processor's standard input or output, and 
whether the pipe is to be opened in binary or text mode. 

The mode string can take one of the following values: 
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jDopen 



Value Description 

rt Read child command's standard output (text). 

rb Read child command's standard output (binary). 

wt Write to child command's standard input (text). 

wb Write to child command's standard input (binary). 



Return value 



See also 



The terminating t or b is optional; if missing, the translation mode is 
determined by the external variable Jmode. 

Use the _pclose function to close the pipe and obtain the return code of the 
command. 

If _popen is successful it returns a FILE pointer that can be used to read the 
standard output of the command, or to write to the standard input of the 
command, depending on the mode string. If jpopen is unsuccessful, it 
returns NULL. 

jpclose, _pipe 



pow, powl 



math.h 



Function 



Calculates x to the power of y. 



Syntax 



Remarks 



pow 
powl 



Return value 



double pow (double x, double y) ; 

long double powl (long double x, double y) ; 
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pow calculates xV. 

powl is the long double version; it takes long double arguments and returns 
a long double result. 

This function can be used with bed and complex types. 

On success, pow and powl return the value calculated, xV. 

Sometimes the arguments passed to these functions produce results that 
overflow or are incalculable. When the correct value would overflow, the 
functions return the value HUGE_VAL (pow) or _LHUGE_VAL (powl). 



140 



Borland C++ for OS/2 Library Reference 



pow, powl 



See also 



Results of excessively large magnitude can cause the global variable errno 
to be set to 

ERANGE Result out of range 

If the argument x passed to pow or powl is real and less than 0, and y is not a 
whole number, or you call pow( 0, ), the global variable errno is set to 



EDOM 



Domain error 



Error handling for these functions can be modified through the functions 
jnatherr and jnatherrl. 

bed, complex, exp, powlO, sqrt 



pow10, powlOI 



math.h 



Function 
Syntax 



pow10 
pow 101 



Remarks 
Return value 



See also 



Calculates 10 to the power of p. 

double powlO(int p) ; 

long double powl01(int p) ; 
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■ 
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powlO computes 10 p . 

On success, powlO returns the value calculated, 10 p . 

The result is actually calculated to long double accuracy. All arguments are 
valid, although some can cause an underflow or overflow. 

powl is the long double version; it returns a long double result. 

exp, pow 



printf 



stdio.h 



Function 
Syntax 



Writes formatted output to stdout. 

int printf (const char *format[, argument, ...]); 



DOS 


UNIX 
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■ 


■ 
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printf 



Remarks 



The format string 



Optional format 
string components 



printf accepts a series of arguments, applies to each a format specifier 
contained in the format string given by format, and outputs the formatted 
data to stdout. There must be the same number of format specifiers as 
arguments. 

The specifiers N and F (discussed below) are provided only to ease porting 
code that was previously written for segmented architectures. In the OS/2 
32-bit flat memory model, near and far pointers are not used. 

This function should not be used in PM applications. 

The format string, present in each of the . . .printf function calls, controls 
how each function will convert, format, and print its arguments. There must 
be enough arguments for the format; if not, the results will be unpredictable and 
possibly disastrous. Excess arguments (more than required by the format) are 
ignored. 

The format string is a character string that contains two types of objects — 
plain characters and conversion specifications: 

■ Plain characters are copied verbatim to the output stream. 

■ Conversion specifications fetch arguments from the argument list and 
apply formatting to them. 

Format specifiers 

...printf format specifiers have the following form: 

% [flags] [width] [.prec] [FlNlhlllL] type 

Each format specifier begins with the percent character (%). After the % 
come the following, in this order: 

b An optional sequence of flag characters, [flags] 

■ An optional width specifier, [width] 

b An optional precision specifier, [ .prec] 

a An optional input-size modifier, [F I N I h 1 1 1 L] 

b The conversion-type character, [type] 

These are the general aspects of output formatting controlled by the 
optional characters, specifiers, and modifiers in the format string: 



Character 
or specifier 



What it controls or specifies 



Flags 



Output justification, numeric signs, decimal points, trailing zeros, octal and hex 
prefixes 
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The specifiers N and F 

are provided only for 

ease of code portability. 



Width Minimum number of characters to print, padding with blanks or zeros 

Precision Maximum number of characters to print; for integers, minimum number of 

digits to print 

Size Override default size of argument: 

N = near pointer 
F = far pointer 
h = short int 
I = long 
L = long double 



...printf 

conversion-type 

characters 



The following table lists the ...printf conversion-type characters, the type of 
input argument accepted by each, and in what format the output appears. 

The information in this table of type characters is based on the assumption 
that no flag characters, width specifiers, precision specifiers, or input-size 
modifiers were included in the format specifiers. To see how the addition of 
the optional characters and specifiers affects the ...printf output, refer to the 
tables following this one. 



Type 
character 



Input argument 



Format of output 




Numerics 

d 
i 

o 
u 

x 
X 

f 

e 

g 

E 
G 

Characters 
c 
s 

% 



Integer 
Integer 
Integer 
Integer 

Integer 
Integer 

Floating-point 

Floating-point 

Floating-point 

Floating-point 
Floating-point 

Character 
String pointer 
None 



signed decimal int. 
signed decimal int. 
unsigned octal int. 
unsigned decimal int. 

unsigned hexadecimal int (with a, b, c, d, e, f). 
unsigned hexadecimal int (with A, B, C, D, E, F). 

signed value of the form [-]dddd.dddd. 

signed value of the form [-]d.ddddor e [+/-]ddd. 

signed value in either e or f form, based on given value and precision. 

Trailing zeros and the decimal point are printed only if necessary. 

Same as e, but with E for exponent. 

Same as g, but with E for exponent if e format used. 



Single character. 

Prints characters until a null-terminator is pressed or precision is reached. 

The % character is printed. 



Chapter 2, Run-time functions 



143 



printf 



Pointers 
n 



Pointer to int Stores (in the location pointed to by the input argument) a count of the 

characters written so far. 

Pointer Prints the argument as a pointer. Eight hexadecimal digits in format XXXXXXXX. 



Conventions Certain conventions accompany some of these specifications. The decimal- 
point character used in the output is determined by the current locale's 
LC_NUMERIC category. The conventions are summarized in the following 
table: 



Characters 



Conventions 



e or E The argument is converted to match the style [-] d.ddd...e[+/-]ddd, where 

■ One digit precedes the decimal point. 

■ The number of digits after the decimal point is equal to the precision. 

■ The exponent always contains at least two digits. 

f The argument is converted to decimal notation in the style [-] ddd.ddd..., where 

the number of digits after the decimal point is equal to the precision (if a nonzero 
precision was given). 

g or G The argument is printed in style e, E or f, with the precision specifying the 

number of significant digits. Trailing zeros are removed from the result, and a 
decimal point appears only if necessary. 

Characters Conventions 

The argument is printed in style e or f (with some restraints) if g is the 
conversion character, and in style E if the character is G. Style e is used only if 
the exponent that results from the conversion is either greater than the precision 
or less than -4. 

x or X For x conversions, the letters a, b, c, d, e, and f appear in the output; for X 

conversions, the letters A, B, C, D, E, and F appear. 

b^- Infinite floating-point numbers are printed as +INF and -INF. An IEEE 
Not-a-Number is printed as +NAN or -NAN. 

Flag characters The flag characters are minus (-), plus (+), sharp (#), and blank (). They can 
appear in any order and combination. 
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Flag 



What it specifies 



Left-justifies the result, pads on the right with blanks. If not given, it right-justifies the 
result, pads on the left with zeros or blanks. 

+ Signed conversion results always begin with a plus (+) or minus (-) sign. 

blank If value is nonnegative, the output begins with a blank instead of a plus; negative 
values still begin with a minus. 

# Specifies that arg is to be converted using an "alternate form." See the following table. 

^^ Plus (+) takes precedence over blank () if both are given. 

Alternate forms If the # flag is used with a conversion character, it has the following effect 
on the argument (arg) being converted: 



Conversion 
character 



How # affects arg 



c,s,d,i,u No effect. 

is prepended to a nonzero arg. 

x or X Ox (or OX) is prepended to arg. 

e, E, or f The result always contains a decimal point even if no digits follow the point. 

Normally, a decimal point appears in these results only if a digit follows it. 

g or G Same as e and E, with the addition that trailing zeros are not removed. 

Width specifiers The width specifier sets the minimum field width for an output value. 

Width is specified in one of two ways: directly, through a decimal digit 
string, or indirectly, through an asterisk (*). If you use an asterisk for the 
width specifier, the next argument in the call (which must be an int) 
specifies the minimum output field width. 

In no case does a nonexistent or small field width cause truncation of a 
field. If the result of a conversion is wider than the field width, the field is 
simply expanded to contain the conversion result. 



Width 
specifier 



How output width is affected 



At least n characters are printed. If the output value has less than n characters, 
the output is padded with blanks (right-padded if -flag given, left-padded 
otherwise). 
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On At least n characters are printed. If the output value has less than n characters, it 

is filled on the left with zeros. 

* The argument list supplies the width specifier, which must precede the actual 

argument being formatted. 

Precision specifiers A precision specification always begins with a period (.) to separate it from 
any preceding width specifier. Then, like width, precision is specified either 
directly through a decimal digit string, or indirectly through an asterisk (*). 
If you use an asterisk for the precision specifier, the next argument in the 
call (treated as an int) specifies the precision. 

If you use asterisks for the width or the precision, or for both, the width 
argument must immediately follow the specifiers, followed by the precision 
argument, then the argument for the data to be converted. 

Precision 

specifier How output precision is affected 

(none given) Precision set to default: 

default = 1 for d, /, o, u, x, X types 

default = 6 for e, E, Hypes 

default = all significant digits for g, G types 

default = print to first null character for s types; no effect on c types 

.0 For d, i, o, u, x types, precision set to default; for e, E, /types, no decimal point 

is printed. 

.n n characters or n decimal places are printed. If the output value has more than 

n characters, the output might be truncated or rounded. (Whether this happens 
depends on the type character.) 

The argument list supplies the precision specifier, which must precede the 
actual argument being formatted. 

^^ If an explicit precision of zero is specified, and the format specifier for the 
field is one of the integer formats (that is, d, i, o, u, x), and the value to be 
printed is 0, no numeric characters will be output for that field (that is, the 
field will be blank). 

Conversion 

character How precision specification (.n) affects conversion 

d .n specifies that at least n digits are 

i printed. If the input argument has less 

o than n digits, the output value is left- 

u padded with zeros. If the input argument 

x has more than n digits, the output value 

X is not truncated. 
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Input-size modifier 



The specifiers N and F 

are provided only for 

ease of code portability. 



.n specifies that n characters are printed 
after the decimal point, and the last digit 
printed is rounded. 

.n specifies that at most n significant 
digits are printed. 

.n has no effect on the output. 

.n specifies that no more than n characters 
are printed. 



The input-size modifier character (F, N, h, I, or L) gives the size of the 
subsequent input argument: 

F = far pointer 
N = near pointer 
h = short int 
/ = long 
L = long double 

The input-size modifiers (F, N, h, I, and L) affect how the'. . .printf functions 
interpret the data type of the corresponding input argument arg. F and N 
apply only to input args that are pointers (%p, %s, and %n). h, L, and L 
apply to input args that are numeric (integers and floating-point). 

h, I, and L override the default size of the numeric data input arguments: / 
and L apply to integer (d, i, o, u, x, X) and floating-point (e, E,f, g, and G) 
types, while h applies to integer types only. Neither h nor / affect character 
(c, s) or pointer (p, n) types. 



I 



The specifiers N and F 

are provided only for 

ease of code portability. 



Return value 
See also 



Input-size 
modifier 



How arg is interpreted 



F arg is read as a far pointer. 

N arg is read as a near pointer. N cannot be used with any conversion in huge 

model. 

h arg is interpreted as a short int for d, i, o, u, x, or X. 

/ arg is interpreted as a long int for d, i, o, u, x, or X; arg is interpreted as a 

double for e, E, f, g, or G. 

L arg is interpreted as a long double for e, E, f, g, or G. 

printf returns the number of bytes output. In the event of error, printf 
returns EOF. 

cprintf ecvt,fprintf,fread,freopen,fscanf putc, puts, putw, scanf sprintf, vprintf 
vsprintf 
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putc 

Function 
Syntax 



Remarks 
Return value 
See also 



stdio.h 



Outputs a character to a stream. 

int putc (int c, FILE *stream) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



putc is a macro that outputs the character c to the stream given by stream. 

On success, putc returns the character printed, c. On error, putc returns EOF. 

fprintf, fputc, fputchar, fputs, fwrite, getc, getchar, printf, putch, putchar, putzv, 
vprintf 



putch 



conio.h 



Function 
Syntax 



Remarks 



Outputs character to screen. 

int putch (int c) ; 



DOS 


UNIX 


Win 16 


: Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



Return value 
See also 

putchar 



putch outputs the character c to the current text window. It is a text mode 
function performing direct video output to the console, putch does not 
translate linefeed characters (\n) into carriage-return/linefeed pairs. 

This function should not be used in PM applications. 

On success, putch returns the character printed, c. On error, it returns EOF. 

cprintf, cputs, getch, getche, putc, putchar 

stdio.h 



Function 
Syntax 



Remarks 



Outputs character on stdout. 

int putchar (int c) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


" 


■ 



putchar{c) is a macro defined to be putcic, stdout). 
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Return value 
See also 



On success, putchar returns the character c. On error, putchar returns EOF. 

fputchar, getc, getchar, printf, putc, putch, puts, putw,freopen, vprintf 



putenv 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Adds string to current environment. 

int putenv (const char *name) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 






■ 



putenv accepts the string name and adds it to the environment of the current 
process. For example, 

putenv ("PATH=C:\\BC" ); 

putenv can also be used to modify an existing name. On DOS and OS/2, 
name must be uppercase. On other systems, name can be either uppercase or 
lowercase, name must not include the equal sign (=). You can set a variable 
to an empty value by specifying an empty string on the right side of the '=' 
sign. This effectively removes the environment variable. Environment 
variables created by putenv can be lower or upper case. 

putenv can be used only to modify the current program's environment. 
Once the program ends, the old environment is restored. The environment 
of the current process is passed to child processes, including any changes 
made by putenv. 

Note that the string given to putenv must be static or global. Unpredictable 
results will occur if a local or dynamic string given to putenv is used after 
the string memory is released. 

On success, putenv returns 0; on failure, -1. 

getenv 



m 



puts 



stdio.h 



Function 
Syntax 



Outputs a string to stdout. 

int puts (const char *s) ; 
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puts 



Remarks 

Return value 
See also 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 




■ 



puts copies the null-terminated string s to the standard output stream 
stdout and appends a newline character. 

This function should not be used in PM applications. 

On successful completion, puts returns a nonnegative value. Otherwise, it 
returns a value of EOF. 

cputs,fputs, gets, printf, putchar , freopen 



puttext 



conio.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Copies text from memory to the text mode screen. 

int puttext (int left, int top, int right, int bottom, void *source); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 






■ 






■ 



puttext writes the contents of the memory area pointed to by source out to 
the onscreen rectangle defined by left, top, right, and bottom. 

All coordinates are absolute screen coordinates, not window-relative. The 
upper left corner is (1,1). 

puttext places the contents of a memory area into the defined rectangle 
sequentially from left to right and top to bottom. 

Each position onscreen takes 2 bytes of memory: The first byte is the 
character in the cell, and the second is the cell's video attribute. The space 
required for a rectangle w columns wide by h rows high is defined as 

bytes = (h rows) x (w columns) x 2 

This function should not be used in PM applications. 

puttext returns a nonzero value if the operation succeeds; it returns if it 
fails (for example, if you gave coordinates outside the range of the current 
screen mode). 

gettext, movetext, window 
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putw 

Function 
Syntax 



Remarks 
Return value 
See also 



stdio.h 



Puts an integer on a stream. 

int putw(int w, FILE *stream) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 






■ 



putw outputs the integer w to the given stream, putw neither expects nor 
causes special alignment in the file. 

On success, putw returns the integer w. On error, putw returns EOF. Because 
EOF is a legitimate integer, use f err or to detect errors with putw. 

getw, printf 



qsort 



stdlib.h 



Function 
Syntax 



Remarks 



Sorts using the quicksort algorithm. 

void qsort (void *base, size_t nelem, size_t width, 

int (JJSERENTRY *fcmp) (const void *, const void *) 



i 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



qsort is an implementation of the "median of three" variant of the quicksort 
algorithm, qsort sorts the entries in a table by repeatedly calling the user- 
defined comparison function pointed to by fcmp. 

■ base points to the base (Oth element) of the table to be sorted. 

■ nelem is the number of entries in the table. 

■ width is the size of each entry in the table, in bytes. 

fcmp, the comparison function, must be used with the _USERENTRY calling 
convention. 

fcmp accepts two arguments, eleml and eleml, each a pointer to an entry in 
the table. The comparison function compares each of the pointed-to items 
(*eleml and *elem2), and returns an integer based on the result of the 
comparison. 

■ *eleml < *elem2 fcmp returns an integer < 
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q'sort 



Return value 
See also 



*eleml == *elem2 
*eleml > *elem2 



fcmp returns 

fcmp returns an integer > 



In the comparison, the less-than symbol (<) means the left element should 
appear before the right element in the final, sorted sequence. Similarly, the 
greater-than (>) symbol means the left element should appear after the 
right element in the final, sorted sequence. 

None. 

bsearch, Isearch 



raise 



signal.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Sends a software signal to the executing program. 

int raise (int sig) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



raise sends a signal of type sig to the program. If the program has installed a 
signal handler for the signal type specified by sig, that handler will be 
executed. If no handler has been installed, the default action for that signal 
type will be taken. 

The signal types currently defined in signal.h are noted here: 



Signal 


Description 


SIGABRT 


Abnormal termination 


SIGFPE 


Bad floating-point operation 


SIGILL 


Illegal instruction 


SIGINT 


Ctrl-C interrupt 


SIGSEGV 


Invalid access to storage 


SIGTERM 


Request for program termination 


SIGUSR1 


User-defined signal 


SIGUSR2 


User-defined signal 


SIGUSR3 


User-defined signal 


SIGBREAK 


Ctrl-Break interrupt 



SIGABRT isn't generated by Borland C++ during normal operation. 
However, it can be generated by abort, raise, or unhandled exceptions. 

raise returns if successful, nonzero otherwise. 

abort, signal 
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rand 

Function 
Syntax 



Remarks 

Return value 
See also 



stdlib.h 



Random number generator. 

int rand (void) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


" j 


■ 


■ 


■ 


■ 


■ 


■ 



rand uses a multiplicative congruential random number generator with 
period 2 32 to return successive pseudorandom numbers in the range from 
to RAND_MAX. The symbolic constant RAND_MAX is defined in stdlib.h. 

rand returns the generated pseudorandom number. 

random, randomize, srand 



random 



stdlib.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Random number generator. 

int random (int num) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



random returns a random number between and (num-1). random(num) is a 
macro defined in stdlib.h. Both num and the random number returned are 
integers. 

random returns a number between and {num-1). 

rand, randomize, srand 



randomize 



stdlib.h, time.h 



Function 
Syntax 



Remarks 



Initializes random number generator. 

void randomize (void); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



randomize initializes the random number generator with a random value. 
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randomize 



Return value 
See also 



None. 

rand, random, srand 



read 



io.h, dos.h 



Remarks 



Obsolete function. See rtl read. 



read 



io.h 



Function 
Syntax 



Remarks 



Return value 



Reads from file. 

int read(int handle, void *buf, unsigned len) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 






■ 



read attempts to read len bytes from the file associated with handle into the 
buffer pointed to by buf. 

For a file opened in text mode, read removes carriage returns and reports 
end-of-file when it reaches a Ctrl-Z. 

The file handle handle is obtained from a creat, open, dup, or dup2 call. 

On disk files, read begins reading at the current file pointer. When the 
reading is complete, it increments the file pointer by the number of bytes 
read. On devices, the bytes are read directly from the device. 

The maximum number of bytes that read can read is UINTJMAX -1, 
because UINTJV1AX is the same as -1, the error return indicator. 
UINTJVIAX is defined in limits.h. 

On successful completion, read returns an integer indicating the number of 
bytes placed in the buffer. If the file was opened in text mode, read does not 
count carriage returns or Ctrl-Z characters in the number of bytes read. 

On end-of-file, read returns 0. On error, read returns -1 and sets the global 
variable errno to one of the following values: 



See also 



EACCES 
EBADF 



Permission denied 
Bad file number 



open, _rtl_read, write 
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readdir 

Function 
Syntax 



Remarks 



dirent.h 



Return value 



See also 



Reads the current entry from a directory stream. 

struct dirent *readdir(DIR *dirp); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


" 






■ 



readdir is available on POSIX-compliant UNIX systems. 

The readdir function reads the current directory entry in the directory 
stream pointed to by dirp. The directory stream is advanced to the next 
entry. 

The readdir function returns a pointer to a dirent structure that is overwrit- 
ten by each call to the function on the same directory stream. The structure 
is not overwritten by a readdir call on a different directory stream. 

The dirent structure corresponds to a single directory entry. It is defined in 
dirent.h, and contains (in addition to other non-accessible members) the 
following member: 

char d_name [ ] ; 

where djiame is an array of characters containing the null-terminated file 
name for the current directory entry. The size of the array is indeterminate; 
use strlen to determine the length of the file name. 

All valid directory entries are returned, including subdirectories, "." and ^^ 
".." entries, system files, hidden files, and volume labels. Unused or deleted Wmft 
directory entries are skipped. pja 

A directory entry can be created or deleted while a directory stream is 
being read, but readdir might or might not return the affected directory 
entry. Rewinding the directory with rewinddir or reopening it with opendir 
ensures that readdir will reflect the current state of the directory. 

If successful, readdir returns a pointer to the current directory entry for the 
directory stream. If the end of the directory has been reached, or dirp does 
not refer to an open directory stream, readdir returns NULL. 

closedir, opendir, rewinddir 



realloc 



stdlib.h 



Function 



Reallocates main memory. 
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realloc 



Syntax 



Remarks 



void *realloc(void *block, size_t size); 



Return value 



See also 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 1 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



realloc attempts to shrink or expand the previously allocated block to size 
bytes. If size is zero, the memory block is freed and NULL is returned. The 
block argument points to a memory block previously obtained by calling 
malloc, calloc, or realloc. If block is a NULL pointer, realloc works just like 
malloc. 

realloc adjusts the size of the allocated block to size, copying the contents to 
a new location if necessary. 

realloc returns the address of the reallocated block, which can be different 
than the address of the original block. If the block cannot be reallocated, 
realloc returns NULL. 

If the value of size is 0, the memory block is freed and realloc returns NULL. 

calloc, free, malloc 



remove 



stdio.h 



Function 
Syntax 



Remarks 



Return value 



Removes a file. 

int remove (const char *filename) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


i 


■ 


■ 


■ 


■ 



remove deletes the file specified by filename. It is a macro that simply 
translates its call to a call to unlink. If your file is open, be sure to close it 
before removing it. 

This function will fail (EACCES) if the file is currently open in any process. 

The filename string can include a full path. 

On successful completion, remove returns 0. On error, it returns -1, and the 
global variable errno is set to one of the following values: 



See also 



EACCES Permission denied 
ENOENT No such file or directory 

unlink 
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rename 

Function 
Syntax 



Remarks 



stdio.h 



Return value 



Renames a file. 

int rename (const char *oldname, const char *newname) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




" 


■ 


■ 


■ 


■ 



rename changes the name of a file from oldname to newname. If a drive 
specifier is given in newname, the specifier must be the same as that given in 
oldname. 

Directories in oldname and newname need not be the same, so rename can be 
used to move a file from one directory to another. Wildcards are not 
allowed. 

On successfully renaming the file, rename returns 0. In the event of error, -1 
is returned, and the global variable errno is set to one of the following 
values: 

EACCES Permission denied: filename already exists or has an 

invalid path, or is open 
ENOENT No such file or directory 
ENOTSAM Not same device 



rewind 



stdio.h 



I 



Function 
Syntax 



Remarks 



Return value 
See also 



Repositions a file pointer to the beginning of a stream. 

void rewind(FILE *stream) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


i 


■ 



rewind(stream) is equivalent to fseek(stream, 0L, SEEK_SET), except that 
rewind clears the end-of-file and error indicators, while fseek clears the end- 
of-file indicator only. 

After rewind, the next operation on an update file can be either input or 
output. 

None. 

fopen, fseek, ft ell 
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rewinddir 



rewinddir 



dirent.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Resets a directory stream to the first entry. 

void rewinddir (DIR *dirp) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


' 


■ 






■ 



rewinddir is available on POSIX-compliant UNIX systems. 

The rewinddir function repositions the directory stream dirp at the first entry 
in the directory. It also ensures that the directory stream accurately reflects 
any directory entries that might have been created or deleted since the last 
opendir or rewinddir on that directory stream. 

None. 

closedir, opendir, readdir 



rmdir 



dir.h 



Function 
Syntax 



Remarks 



Return value 



Removes a directory. 

int rmdir(const char *path) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


" 


■ 


■ 






■ 



See also 



rmdir deletes the directory whose path is given by path. The directory 
named by path 

■ Must be empty 

■ Must not be the current working directory 

■ Must not be the root directory 

rmdir returns if the directory is successfully deleted. A return value of -1 
indicates an error, and the global variable errno is set to one of the following 
values: 

EACCES Permission denied 
ENOENT Path or file function not found 

chdir, getcurdir, getcwd, mkdir 
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rmtmp 

Function 
Syntax 



Remarks 



Return value 



stdio.h 



Removes temporary files. 

int rmtmp (void) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


" 






■ 



The rmtmp function closes and deletes all open temporary file streams, 
which were previously created with tmpfile. The current directory must the 
same as when the files were created, or the files will not be deleted. 

rmtmp returns the total number of temporary files it closed and deleted. 



_rotl, _rotr 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Bit-rotates an unsigned short integer value to the left or right. 

unsigned short _rotl (unsigned short value, int count); 
unsigned short _rotr (unsigned short value, int count); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



_rotl rotates the given value to the left count bits. 

_rotr rotates the given value to the right count bits. 

The functions return the rotated integer: 

■ jot I returns the value of value left-rotated count bits. 
m_rotr returns the value of value right-rotated count bits. 

_crotl, _crotr, Jrotl, Jrotr 



i 



rtl chmod 



dos.h, io.h 



Function 
Syntax 



Gets or sets file attributes. 

int _rtl_chmod (const char *path, int func [, int attrib] ) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 
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rtl chmod 



Remarks 



Return value 



_rtl_chmod can either fetch or set file attributes, lifunc is 0, _rtl_chmod 
returns the current attributes for the file, lifunc is 1, the attribute is set to 

attrib. 

This function will fail (EACCES) if the file is currently open in any process. 
attrib can be one of the following symbolic constants (defined in dos.h): 



FA_RDONLY 

FA_HIDDEN 

FA_SYSTEM 

FA_LABEL 

FA_DIREC 

FA ARCH 



Read-only attribute 
Hidden file 
System file 
Volume label 
Directory 
Archive 



See also 



Upon successful completion, _rtl_chmod returns the file attribute word; 
otherwise, it returns a value of -1. 

In the event of an error, the global variable errno is set to one of the 
following: 

EACCES Permission denied 
ENOENT Path or file name not found 

chmod, _rtl_creat 



rtl close 



io.h 



Function 
Syntax 



Remarks 



Return value 



Closes a file. 

int _rtl_close(int handle); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



_rtl_close closes the file associated with handle, a file handle obtained from a 
_rtl_creat, creat, creatnew, creattemp, dup, dup2, _rtl_open, or open call. 

The function does not write a Ctrl-Z character at the end of the file. If you 
want to terminate the file with a Ctrl-Z, you must explicitly output one. 

Upon successful completion, _rtl_close returns 0. Otherwise, the function 
returns a value of -1. 

_rtl_close fails if handle is not the handle of a valid, open file, and the global 
variable errno is set to 

EBADF Bad file number 
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See also 



chsize, close, creatnew, dup,fclose, _rtl_creat, _rtl_open, sopen 



rtl creat 



dos.h, io.h 



Function 
Syntax 



Remarks 



Return value 



Creates a new file or overwrites an existing one. 

int _rtl_creat (const char *path, int attrib) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



See also 



_rtl_creat opens the file specified by path. The file is always opened in 
binary mode. Upon successful file creation, the file pointer is set to the 
beginning of the file. The file is opened for both reading and writing. 

If the file already exists, its size is reset to 0. (This is essentially the same as 
deleting the file and creating a new file with the same name.) 

The attrib argument is an ORed combination of one or more of the 
following constants (defined in dos.h): 

FA_RDONLY Read-only attribute 
FA_HIDDEN Hidden file 
FA_SYSTEM System file 

Upon successful completion, _rtl_creat returns the new file handle, a non- 
negative integer; otherwise, it returns -1. 

In the event of error, the global variable errno is set to one of the following 
values: 

EACCES Permission denied 
EMFILE Too many open files 

ENOENT Path or file name not found 

chsize, close, creat, creatnew, creattemp, _rtl_chmod, _rtl_close 



i 



_rtl_heapwalk 



malloc.h 



Function 
Syntax 



Inspects the heap, node by node. 

int _rtl_heapwalk(_HEAPINFO *hi) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 








■ 






■ 
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_rtl_heapwalk 



Remarks 



Return value 



_rtl_heapwalk assumes the heap is correct. Use Jieapchk to verify the heap 
before using _rtl_heapzvalk. _HEAPOK is returned with the last block on the 
heap. _HEAPEND will be returned on the next call to _rtl_heapzualk. 

_rtl_heapwalk receives a pointer to a structure of type _HEAPINFO (declared 
in malloc.h). 

For the first call to _rtl_heapwalk, set the hi._pentry field to NULL. 
_rtl_heapwalk returns with hi._pentry containing the address of the first 
block. 

hi._size holds the size of the block in bytes. 

hi.juseflag is a flag that is set to JUSEDENTRY if the block is currently in 
use. If the block is free, hi._useflag is set to _FREEENTRY. 

One of the following values: 

_HEAPBADNODE A corrupted heap block has been found 
_HEAPBADPTR The _pentry field does not point to a valid heap 

block 
_HEAPEMPTY No heap exists 

_HEAPEND The end of the heap has been reached 

_HEAPOK The _heapinfo block contains valid information 

about the next heap block 



_rtl_open 



fcntl.h, share.h, io.h 



Function 
Syntax 



Remarks 



Opens an existing file for reading or writing. 

int _rtl_open (const char *filename, int of lags); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




" 


■ 






■ 



_rtl_open opens the file specified by filename, then prepares it for reading or 
writing, as determined by the value of oflags. The file is always opened in 
binary mode. 

oflags uses the flags from the following two lists. Only one flag from the 
first list can be used (and one must be used); the remaining flags can be 
used in any logical combination. 

List 1 : Read/write flags 

0_RDONLY Open for reading. 
0_WRONLY Open for writing. 
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These symbolic 
constants are defined 
in fcntl.h and share.h. 



Return value 



See also 



0_RDWR Open for reading and writing. 

The following additional values can be included in oflags (using an OR 
operation): 

List 2: Other access flags 



O.NOINHERIT 

SH_COMPAT 

SH_DENYRW 

SH_DENWR 

SH_DENYRD 

SH DENYNO 



The file is not passed to child programs. 
Identical to SH_DENYNO. 

Only the current handle can have access to the file. 
Allow only reads from any other open to the file. 
Allow only writes from any other open to the file. 
Allow other shared opens to the file. 



Only one of the SHJDENYxx values can be included in a single _rtl_open. 
These file-sharing attributes are in addition to any locking performed on 
the files. 

The maximum number of simultaneously open files is defined by 
HANDLE_MAX. 

On successful completion, _rtl_open returns a nonnegative integer (the file 
handle). The file pointer, which marks the current position in the file, is set 
to the beginning of the file. 

On error, _rtl_open returns -1. The global variable errno is set to one of the 
following: 



EACCES 

EINVACC 

EMFILE 

ENOENT 



Permission denied 
Invalid access code 
Too many open files 
Path or file not found 



open, _rtl_read, sopen 



IB 



rtl read 



io.h, dos.h 



Function 
Syntax 



Remarks 



Reads from file. 

int _rtl_read(int handle, void *buf, unsigned len) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 








■ 



_rtl_read attempts to read len bytes from the file associated with handle into 
the buffer pointed to by buf. 
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ill read 



Return value 



See also 



When a file is opened in text mode, _rtl_read does not remove carriage 
returns. 

The argument handle is a file handle obtained from a creat, open, dup, or dup2 
call. 

On disk files _rtl_read begins reading at the current file pointer. When the 
reading is complete, the function increments the file pointer by the number 
of bytes read. On devices, the bytes are read directly from the device. 

The maximum number of bytes that _rtl_read can read is UINT_MAX -1, 
because UINT_MAX is the same as -1, the error return indicator. 
UINT.MAX is defined in limits.h. 

On successful completion, _rtl_read returns a positive integer indicating the 
number of bytes placed in the buffer. On end-of-file, _rtl_read returns zero. 
On error, it returns -1, and the global variable errno is set to one of the 
following values: 



EACCES 
EBADF 



Permission denied 
Bad file number 



read, _rtl_open, _rtl_write 



rtl write 



io.h 



Function 
Syntax 



Remarks 



Writes to a file. 

int _rtl_write(int handle, void *buf, unsigned len) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



_rtl_write attempts to write len bytes from the buffer pointed to by buf to the 
file associated with handle. The maximum number of bytes that _rtl_write 
can write is UINTJMAX -1, because UINTJV1AX is the same as -1, which is 
the error return indicator for _rtl_write. UINT_MAX is defined in limits.h. 
_rtl_zvrite does not translate a linefeed character (LF) to a CR/LF pair 
because all its files are binary files. 

If the number of bytes actually written is less than that requested, the 
condition should be considered an error and probably indicates a full disk. 

For disk files, writing always proceeds from the current file pointer. On 
devices, bytes are directly sent to the device. 
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Return value 



See also 



For files opened with the 0_APPEND option, the file pointer is not 
positioned to EOF by _rtl_zvrite before writing the data. 

_rtl_write returns the number of bytes written. In case of error, _rtl_zurite 
returns -1 and sets the global variable errno to one of the following values: 



EACCES 
EBADF 



Permission denied 
Bad file number 



Iseek, _rtl_read, write 



scant 



stdio.h 



Function 
Syntax 



Remarks 



The format string 



Scans and formats input from the stdin stream. 

int scanf (const char * format [, address, ...]); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 




■ 


■ 


■ 


■ 



scanf scans a series of input fields, one character at a time, reading from the 
stdin stream. Then each field is formatted according to a format specifier 
passed to scanf In the format string pointed to by format. Finally, scanf stores 
the formatted input at an address passed to it as an argument following 
format. There must be the same number of format specifiers and addresses 
as there are input fields. 

The specifiers N and F (discussed below) are provided only to ease porting 
code that was previously written for segmented architectures. In the OS/2 
32-bit flat memory model, near and far pointers are not used. 

This function should not be used in PM applications. 

The format string present in scanf and the related functions cscanf f scanf, 
sscanf vscanf vf scanf, and vsscanf controls how each function scans, 
converts, and stores its input fields. There must be enough address arguments 
for the given format specifiers; if not, the results will be unpredictable and possibly 
disastrous. Excess address arguments (more than required by the format) 
are ignored. 

scanf often leads to unexpected results if you diverge from an expected 
pattern. You need to remember to teach scanf how to synchronize at the end 
of a line. The combination of gets orfgets followed by sscanf is safe and easy, 
and therefore preferred. 

The format string is a character string that contains three types of objects: 
whitespace characters, non-whitespace characters, and format specifiers. 



I 
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Optional format 
string components 



d The whitespace characters are blank, tab (\t) or newline (\n). If a . . .scanf 
function encounters a whitespace character in the format string, it will 
read, but not store, all consecutive whitespace characters up to the next 
non-whitespace character in the input. 

■ The non-whitespace characters are all other ASCII characters except the 
percent sign (%). If a ...scanf function encounters a non-whitespace 
character in the format string, it will read, but not store, a matching non- 
whitespace character. 

■ The format specifiers direct the . . .scanf functions to read and convert 
characters from the input field into specific types of values, then store 
them in the locations given by the address arguments. 

Trailing whitespace is left unread (including a newline), unless explicitly 
matched in the format string. 

Format specifiers 

... .scanf format specifiers have the following form: 

% [*] [width] [FIN] [h|l|L] type_character 

Each format specifier begins with the percent character (%). After the % 
come the following, in this order: 

■ An optional assignment-suppression character, [ * ] 

■ An optional width specifier, [width] 

■ An optional pointer size modifier, [ F I N] 

■ An optional argument-type modifier, [h 1 1 1 L] 
d The type character 

These are the general aspects of input formatting controlled by the optional 
characters and specifiers in the . . .scanf format string: 



The specifiers N and 

F are provided only 

for ease of code 

portability. 



Character 
or specifier 



width 



size 



argument 
type 



What it controls or specifies 



Suppresses assignment of the next input field. 

Maximum number of characters to read; fewer characters might be read if 
the ...scanf function encounters a whitespace or unconvertible character. 

Overrides default size of address argument: 

N = near pointer 
F= far pointer 

Overrides default type of address argument: 
h = short int 
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/= long int (if the type character specifies an integer conversion) 
/ = double (if the type character specifies a floating-point conversion) 
L = long double (valid only with floating-point conversions) 



...scanftype 
characters 



The following table lists the . . .scanftype characters, the type of input 
expected by each, and in what format the input will be stored. 

The information in this table is based on the assumption that no optional 
characters, specifiers, or modifiers (*, width, or size) were included in the 
format specifier. 

To see how the addition of the optional elements affects the . . .scanf input, 
refer to the tables following this one. 



Type 
character 



Expected input 



Type of argument 



Numerics 

d 
D 

o 




e,E 



g.e 



Decimal integer 
Decimal integer 

Octal integer 
Octal integer 

Decimal, octal, or 
hexadecimal integer 
Decimal, octal, or 
hexadecimal integer 

Unsigned decimal 
integer 

Unsigned decimal 
integer 

Hexadecimal integer 
Hexadecimal integer 

Floating point 

Floating point 

Floating point 



Pointer to int (int *arg). 
Pointer to long (long *arg). 

Pointer to int (int *arg). 
Pointer to long (long *arg). 

Pointer to int (int *arg). 
Pointer to long (long *arg). 

Pointer to unsigned int (unsigned int *arg). 
Pointer to unsigned long (unsigned long *arg). 

Pointer to int (int *arg). 
Pointer to int (int *arg). 

Pointer to float (float *arg). 

Pointer to float (float *arg). 

Pointer to float (float *arg). 



I 



Characters 
s 
c 



Character string 
Character 



% character 



Pointer to array of characters (char arg[]). 

Pointer to character (char *arg) if a field width W is given along with the c- 
type character (such as %5c). 

Pointer to array of W characters (char arg[W\). 

No conversion done; % is stored. 
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Type 
character 



Expected input 



Type of argument 



Pointers 
n 



Hexadecimal form 

xxxxxxxx 



Pointer to int (int *arg). The number of characters read successfully up to %n 
is stored in this int. 

Pointer to an object. 



Input fields Any one of the following is an input field: 

■ All characters up to (but not including) the next whitespace character 

■ All characters up to the first one that cannot be converted under the 
current format specifier (such as an 8 or 9 under octal format) 

■ Up to n characters, where n is the specified field width 

Conventions Certain conventions accompany some of these format specifiers. The 

decimal-point character used in the output is determined by the current 
locale's LC_NUMERIC category. The conventions are summarized here. 

%c conversion 

This specification reads the next character, including a whitespace charac- 
ter. To skip one whitespace character and read the next non-whitespace 
character, use %ls. 

% Wc conversion (W = width specification) 

The address argument is a pointer to an array of characters; the array 
consists of W elements (char arg[W\). 

%s conversion 

The address argument is a pointer to an array of characters (char arg[]). 

The array size must be at least (n+1) bytes, where n equals the length of 
string s (in characters). A space or newline terminates the input field; the 
terminator is not scanned or stored. A null-terminator is automatically 
appended to the string and stored as the last element in the array. 

%[search_set] conversion 

The set of characters surrounded by square brackets can be substituted for 
the s-type character. The address argument is a pointer to an array of 
characters (char arg[]). 

These square brackets surround a set of characters that define a search set of 
possible characters making up the string (the input field). 

If the first character in the brackets is a caret ( A ), the search set is inverted to 
include all ASCII characters except those between the square brackets. 
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(Normally, a caret will be included in the inverted search set unless 
explicitly listed somewhere after the first caret.) 

The input field is a string not delimited by whitespace. .. .scanf reads the 
corresponding input field up to the first character it reaches that does not 
appear in the search set (or in the inverted search set). Two examples of this 
type of conversion are 

I [abed] Searches for any of the characters a, b, c, and d in the input 

field. 
% [ A abcd] Searches for any characters except a, b, c, and d in the input 

field. 

You can also use a range facility shortcut to define a range of characters 
(numerals or letters) in the search set. For example, to catch all decimal 
digits, you could define the search set by using % [0123456789], or you could 
use the shortcut to define the same search set by using % [0-9] . 

To catch alphanumeric characters, use the following shortcuts: 

% [A-Z] Catches all uppercase letters. 

% [0-9A-Za-z] Catches all decimal digits and all letters (uppercase and 

lowercase). 
%[A-FT-Z] Catches all uppercase letters from A through F and from 

T through Z. 

The rules covering these search set ranges are straightforward: 

■ The character prior to the hyphen (-) must be lexically less than the one 
after it. 

a The hyphen must not be the first nor the last character in the set. (If it is 
first or last, it is considered to be the hyphen character, not a range 
definer.) 

■ The characters on either side of the hyphen must be the ends of the range 
and not part of some other range. 

Here are some examples where the hyphen just means the hyphen 
character, not a range between two ends: 

%[-+*/] The four arithmetic operations. 

% [ z - a ] The characters z, -, and a . 

I [ + - 9 - A- Z ] The characters + and - and the ranges 0-9 and A-Z. 
% [+0-9A-Z-] Also the characters + and - and the ranges 0-9 and A-Z. 
% [ A - - 9 +A- Z ] All characters except + and - and those in the ranges 0-9 
and A-Z. 




Chapter 2, Run-time functions 169 



scant 



INF = INFinity; NAN = 

Not-A-Number 



Assignment- 
suppression 
character 



%e, %E. %f, %g, and %G (floating-point) conversions 

Floating-point numbers in the input field must conform to the following 
generic format: 

[+/-] ddddddddd [.] dddd [E I e] [+/-] ddd 

where [item] indicates that item is optional, and ddd represents decimal, 
octal, or hexadecimal digits. 

In addition, +INF, -INF, +NAN, and -NAN are recognized as floating- 
point numbers. Note that the sign and capitalization are required. 

%d, %i, %o, %x, %D, %l, %0, %X, %c, %n conversions 

A pointer to unsigned character, unsigned integer, or unsigned long can be 

used in any conversion where a pointer to a character, integer, or long is 

allowed. 

The assignment-suppression character is an asterisk (*); it is not to be 
confused with the C indirection (pointer) operator (also an asterisk). 

If the asterisk follows the percent sign (%) in a format specifier, the next 
input field will be scanned but not assigned to the next address argument. 
The suppressed input data is assumed to be of the type specified by the 
type character that follows the asterisk character. 

The success of literal matches and suppressed assignments is not directly 
determinable. 

Width specifiers The width specifier (n), a decimal integer, controls the maximum number of 
characters that will be read from the current input field. 

If the input field contains fewer than n characters, . . .scan/ reads all the 
characters in the field, then proceeds with the next field and format 
specifier. 

If a whitespace or nonconvertible character occurs before width characters 
are read, the characters up to that character are read, converted, and stored, 
then the function attends to the next format specifier. 

A nonconvertible character is one that cannot be converted according to the 
given format (such as an 8 or 9 when the format is octal, or a / or K when 
the format is hexadecimal or decimal). 



Width 
specifier 



How width of stored input is affected 



Up to n characters are read, converted, and stored in the current address 
argument. 
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Input-size and 

argument-type 

modifiers 



The input-size modifiers (N and F) and argument-type modifiers (h, I, and 
L) affect how the . . .scanf functions interpret the corresponding address 
argument arg[f]. 

F and N override the default or declared size of arg. 

h, I, and L indicate which type (version) of the following input data is to be 
used (h = short, / = long, L = long double). The input data will be converted 
to the specified version, and the arg for that input data should point to an 
object of the corresponding size (short object for %h, long or double object 
for %l, and long double object for %L). 



Modifier 



How conversion is affected 



The specifiers N and 

F are provided only 

for ease of code 

portability. 



When scanf stops 
scanning 



F Overrides default or declared size; arg interpreted as far pointer. 

N Overrides default or declared size; arg interpreted as near pointer. Cannot be 

used with any conversion in huge model. 

h For d, i, o, u, /types, convert input to short int, store in short object. 

For D, I, 0, U, X types, no effect. 

For e, f, c, s, n, p types, no effect. 
I For d, i, o, u, x types, convert input to long int, store in long object. 

For e, f, g types, convert input to double, store in double object. 

For D, /, 0, U, X types, no effect. 

For c, s, n, p types, no effect. 

L For e, f, g types, convert input to a long double, store in long double object. L 

has no effect on other formats. 

scanf might stop scanning a particular field before reaching the normal 
field-end character (whitespace), or might terminate entirely, for a variety 
of reasons. 

scanf stops scanning and storing the current field and proceed to the next 
input field if any of the following occurs: 

m An assignment-suppression character (*) appears after the percent 
character in the format specifier; the current input field is scanned but 
not stored. 

d width characters have been read (width = width specification, a positive 
decimal integer in the format specifier). 

□ The next character read cannot be converted under the current format 
(for example, an A when the format is decimal). 

□ The next character in the input field does not appear in the search set (or 
does appear in an inverted search set). 
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Return value 



See also 



When scanf stops scanning the current input field for one of these reasons, 
the next character is assumed to be unread and to be the first character of 
the following input field, or the first character in a subsequent read 
operation on the input. 

scanf will terminate under the following circumstances: 

■ The next character in the input field conflicts with a corresponding non- 
whitespace character in the format string. 

■ The next character in the input field is EOF. 

■ The format string has been exhausted. 

If a character sequence that is not part of a format specifier occurs in the 
format string, it must match the current sequence of characters in the input 
field; scanf will scan but not store the matched characters. When a 
conflicting character occurs, it remains in the input field as if it were never 
read. 

scanf returns the number of input fields successfully scanned, converted, 
and stored; the return value does not include scanned fields that were not 
stored. If scanf attempts to. read at end-of-file, the return value is EOF. If no 
fields were stored, the return value is 0. 

atof cscanf f scanf, freopen, getc, printf sscanf, vf scanf, vscanf, vsscanf 



searchenv 



stdlib.h 



Function 
Syntax 



Searches an environment path for a file. 

void _searchenv (const char *file, const char *varname, char *buf ) ; 



Remarks 
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Win 16 
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■ 
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■ 



_searchenv attempts to locate file, searching along the path specified by the 
operating system environment variable varname. Typical environment 
variables that contain paths are PATH, LIB, and INCLUDE. 

_searchenv searches for the file in the current directory of the current drive 
first. If the file is not found there, the environment variable varname is 
fetched, and each directory in the path it specifies is searched in turn until 
the file is found, or the path is exhausted. 

When the file is located, the full path name is stored in the buffer pointed to 
by buf This string can be used in a call to access the file (for example, with 
fopen or exec. ..). The buffer is assumed to be large enough to store any 
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Return value 
See also 



possible file name. If the file cannot be successfully located, an empty string 
(consisting of only a null character) will be stored at buf. 

None. 

_dosJindfirst, _dos_Jindnext, exec. . ., spawn..., system 



searchpath 



dir.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Searches the operating system path for a file. 

char *searchpath (const char *file); 
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searchpath attempts to locate file, searching along the operating system path, 
which is the PATH=. . . string in the environment. A pointer to the complete 
path-name string is returned as the function value. 

searchpath searches for the file in the current directory of the current drive 
first. If the file is not found there, the PATH environment variable is 
fetched, and each directory in the path is searched in turn until the file is 
found, or the path is exhausted. 

When the file is located, a string is returned containing the full path name. 
This string can be used in a call to access the file (for example, with fopen or 
exec...). 

The string returned is located in a static buffer and is overwritten on each 
subsequent call to searchpath. 

searchpath returns a pointer to a file name string if the file is successfully 
located; otherwise, searchpath returns null. 

exec. ..,findfirst,findnext, spawn.. ., system 




searchstr 



stdlib.h 



Function 
Syntax 



Searches a list of directories for a file. 

void _searchstr (const char *file, const char *ipath, char *buf) 
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Remarks 



Return value 
See also 



_searchstr attempt to locate file, searching along the path specified by the 
string ipath. 

_searchstr searches for the file in the current directory of the current drive 
first. If the file is not found there, each directory in ipath is searched in turn 
until the file is found, or the path is exhausted. The directories in ipath must 
be separated by semicolons. 

When the file is located, the full path name is stored in the buffer pointed 
by by buf. This string can be used in a call to access the file (for example, 
with fopen or exec. . .). The buffer is assumed to be large enough to store any 
possible file name. The constant _MAX_PATH, defined in stdlib.h, is the 
size of the largest file name. If the file cannot be successfully located, an 
empty string (consisting of only a null character) will be stored at buf. 

None. 

searchenv 



setbuf 



stdio.h 



Function 
Syntax 



Remarks 



Assigns buffering to a stream. 

void setbuf (FILE *stream, char *buf) 
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setbuf causes the buffer buf to be used for I/O buffering instead of an 
automatically allocated buffer. It is used after stream has been opened. 

If buf is null, I/O will be unbuffered; otherwise, it will be fully buffered. 
The buffer must be BUFSIZ bytes long (specified in stdio.h). 

stdin and stdout are unbuffered if they are not redirected; otherwise, they 
are fully buffered, setbuf can be used to change the buffering style used. 

Unbuffered means that characters written to a stream are immediately 
output to the file or device, while buffered means that the characters are 
accumulated and written as a block. 

setbuf produces unpredictable results unless it is called immediately after 
opening stream or after a call to fseek. Calling setbuf 'after stream has been 
unbuffered is legal and will not cause problems. 
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Return value 
See also 



A common cause for error is to allocate the buffer as an automatic (local) 
variable and then fail to close the file before returning from the function 
where the buffer was declared. 

None. 

fflush,fopen,fseek, setvbuf 



_setcursortype 



conio.h 



Function 
Syntax 



Remarks 



Return value 



Selects cursor appearance. 

void _setcursortype(int cur_t); 
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Sets the cursor type to 

_NOCURSOR 
_NORMALCURSOR 
SOLIDCURSOR 



Turns off the cursor 
Normal underscore cursor 
Solid block cursor 



This function should not be used in PM applications. 
None. 



setdate 



setdisk 



See _dos_getdate on page 45. 




See getdisk. 



setjmp 



setjmp.h 



Function 
Syntax 



Sets up for nonlocal goto. 

int setjmp (jmp_buf jrapb) ; 
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Remarks 
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setjmp captures the complete task state in jmpb and returns 0. 

A later call to longjmp with jmpb restores the captured task state and returns 
in such a way that setjmp appears to have returned with the value vol. 

A task state includes: 

■ no segment registers are saved 

■ register variables (EBX, EDI, ESI) 
b stack pointer (ESP) 

■ frame base pointer (EBP) 

■ flags are not saved 



Return value 
See also 



setjmp must be called before longjmp. The routine that calls setjmp and sets 
up jmpb must still be active and cannot have returned before the longjmp is 
called. If it has returned, the results are unpredictable. 

setjmp is useful for dealing with errors and exceptions encountered in a 
low-level subroutine of a program. 

setjmp returns when it is initially called. If the return is from a call to 
longjmp, setjmp returns a nonzero value (as in the example). 

longjmp, signal 



setlocale 



locale.h 



Function 
Syntax 



Remarks 



Selects or queries a locale. 

char *setlocale(int category, const char *locale); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 


■ 


■ 


■ 



Borland C++ supports the following locales at present: 



Future releases of 

Borland C++ will 

increase the number 

of locales supported. 



Module Locale supported 



de_DE German 

fr_FR French 

en_GB English (Great Britain) 

enJJS English (United States) 
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For each locale, the following character sets are supported: 

DOS437 English 

DOS850 Multilingual (Latin I) 

WIN1252 Windows, Multilingual 

For a description of DOS character sets, see MS-DOS User's Guide and 
Reference. See also MS Windows 3.1 Programmer's Reference, Volume 4 for a 
discussion of the WIN1252 character set. 

The possible values for the category argument are as follows: 



Value 



Description 



The LOCALE.BLL file 

is installed in BC0S2\ 

BIN directory. 



LC_ALL 

LC_COLLATE 

LC_CTYPE 

LC.MONETARY 
LC_NUMERIC 

LC TIME 



Affects all the following categories. 

Affects strcoll and strxfrm. 

Affects single-byte character handling functions. The mbstowcs and mbtowc 
functions are not affected. 

Affects monetary formatting by the localeconv function. • 

Affects the decimal point of non-monetary data formatting. This includes the 
printf family of functions, and the information returned by localeconv. 

Affects strftime. 



The locale argument is a pointer to the name of the locale or named locale 
category. Passing a NULL pointer returns the current locale in effect. 
Passing a pointer that points to a null string requests setlocale to look for 
environment variables to determine which locale to set. The locale names 
are case sensitive. 

If you specify a locale other than the default C locale, setlocale tries to access 
the locale library file named LOCALE.BLL to obtain the locale data. This 
file is located using the following strategies: 

1. Searching the directory where the application's executable resides. 

2. Searching in the current default directory. 

3. Accessing the "PATH" environment variable and searching in each of 
the specified directories. 

If the locale library is not found, setlocale terminates. 

When setlocale is unable to honor a locale request, the preexisting locale in 
effect is unchanged and a null pointer is returned. 

If the locale argument is a NULL pointer, the locale string for the category is 
returned. If category is LC_ALL, a complete locale string is returned. The 
structure of the complete locale string consists of the names of all the 
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categories in the current locale concatenated and separated by semicolons. 
This string can be used as the locale parameter when calling setlocale with 
LC_ALL. This will reinstate all the locale categories that are named in the 
complete locale string, and allows saving and restoring of locale states. If 
the complete locale string is used with a single category, for example, 
LC_TIME, only that category will be restored from the locale string. 

ANSI C states that if an empty string "" is used as the locale parameter an 
implementation defined locale is used, setlocale has been implemented to 
look for corresponding environment variables in this instance as POSIX 
suggests. 

If the environment variable LC_ALL exists, the category will be set 
according to this variable. If the variable does not exist, the environment 
variable that has the same name as the requested category is looked for and 
the category is set accordingly. 

If none of the above are satisfied, the environment variable named LANG is 
used. Otherwise, setlocale fails and returns a NULL pointer. 



To take advantage of dynamically loadable locales in your application, 
define USELOCALES for each module. If USELOCALES is not 



See the 
Programmers Guide, 

information about defined, all locale-sensitive functions and macros will work only with the 
defining options, default C locale. 



If a NULL pointer is used as the argument for the locale parameter, setlocale 
returns a string that specifies the current locale in effect. If the category 
parameter specifies a single category, such as LC_COLLATE, the string 
pointed to will be the name of that category. If LC_ALL is used as the 
category parameter then the string pointed to will be a full locale string that 
will indicate the name of each category in effect. 

localenameptr = setlocale! LC_COLLATE, NULL ); 

if (localenameptr) 

printf( "%s\n", localenameptr ); 

The output here will be one of the module names together with the 
specified code page. For example, the output could be fr_FR.DOS850@dbase. 

localenameptr = setlocale ( LC_ALL, NULL ); 

if (localenameptr) 

printff "%s\n", localenameptr ); 

An example of the output here could be the following: 
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The default collation 

is named dbase. 

Therefore, whether 

you specify dbase or 

nothing at all, you get 

the same collation. 

However, dbase 

might not be the 

default in future 

releases. 



Return value 



See also 



fr_FR.DOS850@dbase;fr_FR.DOS850;fr_FR.DOS850;fr_FR.DOS850; 
fr_FR.DOS850;fr_FR.DOS850;; 

Each category in this full string is delimited by a semicolon. This string can 
be copied and saved by an application and then used again to restore the 
same locale categories at another time. Each delimited name corresponds to 
the locale category constants defined in locale.h. Therefore, the first name is 
the name of the LC_COLLATE category, the second is the LC_CTYPE 
category, and so on. Any other categories named in the locale.h header file 
are reserved for future implementation. 

Here are some examples of setting locales by using setlocale: 

Set all default categories for the specified French locale: 

setlocale( LC_ALL, "fr_FR.DOS850" ); 

Set French locale to named collation dbase: 

setlocale ( LC_COLLATE, "fr_FR.DOS850@dbase" ) 

When a category is loaded from the locale library, the default category is 
the one that will be loaded unless a modifier name is used. For example: 

setlocale( LC_COLLATE, "fr_FR.DOS850" ) 

causes the default LC_COLLATE category to be loaded. It might or might 
not have a specific name. 

setlocale ( LC_COLLATE, "fr_FR.DOS850@dbase" ) 

specifies that the LC_COLLATE category named dbase to be loaded. This 
might or might not be the default. 

setlocale updates the Iconv locale structure when a request has been fulfilled. 

When an application exits, any allocated memory used for the locale object 
is deallocated. 

If selection is successful, setlocale returns a pointer to a string that is associ- 
ated with the selected category (or possibly all categories) for the new 
locale. 

On failure, a NULL pointer is returned and the locale is unchanged. All 
other possible returns are discussed in the Remarks section above. 

localeconv 




setmode 



fcntl.h 



Function 



Sets mode of an open file. 
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Syntax 



Remarks 



Return value 



See also 



int setmodefint handle, int amode) ; 
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setmode sets the mode of the open file associated with handle to either binary 
or text. The argument amode must have a value of either 0_BINARY or 
OJTEXT, never both. (These symbolic constants are defined in fcntl.h.) 

setmode returns the previous translation mode if successful. On error it 
returns -1 and sets the global variable errno to 

EINVAL Invalid argument 

creat, open, _rtl_creat, _rtl_open 



settime 



See gettime on page 94. 



setvbuf 



stdio.h 



Function 
Syntax 



Remarks 



Assigns buffering to a stream. 

int setvbuf (FILE *stream, char *buf, int type, size_t size) 
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setvbuf causes the buffer buf to be used for I/O buffering instead of an 
automatically allocated buffer. It is used after the given stream is opened. 

If buf is null, a buffer will be allocated using malloc; the buffer will use size 
as the amount allocated. The buffer will be automatically freed on close. 
The size parameter specifies the buffer size and must be greater than zero. 

The parameter size is limited by the constant UINTJV1AX as defined in 
limits.h. 

stdin and stdout are unbuffered if they are not redirected; otherwise, they 
are fully buffered. Unbuffered means that characters written to a stream are 
immediately output to the file or device, while buffered means that the 
characters are accumulated and written as a block. 

The type parameter is one of the following: 
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Return value 
See also 



■ _IOFBF The file is fully buffered. When a buffer is empty, the next 

input operation will attempt to fill the entire buffer. On 
output, the buffer will be completely filled before any data is 
written to the file. 

■ _IOLBF The file is line buffered. When a buffer is empty, the next input 

operation will still attempt to fill the entire buffer. On output, 
however, the buffer will be flushed whenever a newline 
character is written to the file. 

a _IONBF The file is unbuffered. The bufaxvd size parameters are 

ignored. Each input operation will read directly from the 
file, and each output operation will immediately write the 
data to the file. 

A common cause for error is to allocate the buffer as an automatic (local) 
variable and then fail to close the file before returning from the function 
where the buffer was declared. 

setvbuf returns on success. It returns nonzero if an invalid value is given 
for type or size, or if there is not enough space to allocate a buffer. 

fflush,fopen, setbuf 



setverify 



dos.h 



Function 
Syntax 



Sets the state of the verify flag in the operating system. 



void setverify (int value); 



Remarks 



Return value 
See also 
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setverify sets the current state of the verify flag to value, which can be either 
(off) or 1 (on). 

The verify flag controls output to the disk. When verify is off, writes are not 
verified; when verify is on, all disk writes are verified to ensure proper 
writing of the data. 

None. 

getverify 
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signal 

Function 
Syntax 



Remarks 



signal.h 



Specifies signal-handling actions. 

void (JJSERENTRY *signal(int sig, void (JJSERENTRY *func) 

(int sig[, int subcode] ))) (int) 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



signal determines how receipt of signal number sig will subsequently be 
treated. You can install a user-specified handler routine (specified by the 
argument func) or use one of the two predefined handlers, SIG_DFL and 
SIG_IGN, in signal.h. The function func must be used with the 
JJSERENTRY calling convention. 



Function pointer 



Description 



SIG_DFL 
SIG_ERR 
SIG IGN 



Terminates the program 

Indicates an error return from signal 

Ignore this type signal 



The signal types and their defaults are as follows: 



Signal type 



Description 



SIGBREAK Control-Break interrupt. Keyboard must be in raw mode. Default 

action is to terminate the program. 

SIGABRT Abnormal termination. Default action is equivalent to printing 

Abnormal program termination to stderr and calling 
_exit{3). 

SIGFPE Arithmetic error caused by division by 0, invalid operation, and 

the like. Default action is program termination. 

SIGILL Illegal operation. Default action is program termination. 

SIGINT Ctrl-C interrupt. Default action is program termination. 

SIGSEGV Illegal storage access. Default action is program termination. 

SIGTERM Request for program termination. Default action is program 

termination. 

SIGUSR1 , User-defined signals that can be generated only 

SIGUSR2, by calling raise. Default action is to ignore 

SIGUSR3 the signal. 

signal.h defines a type called sig_atomic_t, the largest integer type the 
processor can load or store atomically in the presence of asynchronous 
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interrupts (for the 8086 family, this is a 16-bit word; for 80386 and higher 
number processors, it is a 32-bit word — a Borland C++ integer). 

When a signal is generated by the raise function or by an external event, the 
following two things happen: 

■ If a user-specified handler has been installed for the signal, the action for 
that signal type is set to SIG_DFL. 

■ The user-specified function is called with the signal type as the 
parameter. 

User-specified handler functions can terminate by a return or by a call to 
abort, _exit, exit, or longjmp. If your handler function is expected to continue 
to receive and handle more signals, you must have the handler function call 
signal again. 

Borland C++ implements an extension to ANSI C when the signal type is 
SIGFPE, SIGSEGV, or SIGILL. The user-specified handler function is called 
with one or two extra parameters. If SIGFPE, SIGSEGV, or SIGILL has been 
raised as the result of an explicit call to the raise function, the user-specified 
handler is called with one extra parameter, an integer specifying that the 
handler is being explicitly invoked. The explicit activation values for 
SIGFPE, SIGSEGV and SIGILL are as follows (see declarations in float.h): 

Signal Meaning 

SIGFPE FPE_EXPLICITGEN 

SIGSEGV SEGV_EXPLICITGEN 
SIGILL ILL EXPUCITGEN 



If SIGFPE is raised because of a floating-point exception, or SIGSEGV, 
SIGILL, or the integer-related variants of SIGFPE signals 
(FPEJNTOVFLOW or FPEJNTDIVO) are raised as the result of a processor 
exception, the user handler is called with one of SIGFPE, SIGSEGV, or 
SIGILL exception type (see float.h for all these types). This first parameter is 
the usual ANSI signal type. 

The following SIGFPE-type signals can occur (or be generated). They 
correspond to the exceptions that the 8087 family is capable of detecting, as 
well as the "INTEGER DIVIDE BY ZERO" and the "INTERRUPT ON 
OVERFLOW" on the main CPU. (The declarations for these are in float.h.) 

SIGFPE signal Meaning 

FPEJNTOVFLOW INTO executed with OF flag set 

FPEJNTDIVO Integer divide by zero 

FPEJNVALID Invalid operation 
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FPE_ZERODIVIDE Division by zero 

FPE_OVERFLOW Numeric overflow 

FPEJJNDERFLOW Numeric underflow 

FPEJNEXACT Precision 

FPE_EXPLICITGEN User program executed ra/se(SIGFPE) 

FPE_STACKFAULT Floating-point stack overflow or underflow 

The FPEJNTOVFLOW and FPEJNTDIVO signals are generated by integer 
operations, and the others are generated by floating-point operations. 
Whether the floating-point exceptions are generated depends on the 
coprocessor control word, which can be modified with _control87. 
Denormal exceptions are handled by Borland C++ and not passed to a 
signal handler. 

The following SIGSEGV-type signals can occur: 

SEGV_BOUND Bound constraint exception 

SEGV_EXPLICITGEN raz'se(SIGSEGV) was executed 

SEGV_ACCESS Access violation 

SEGV_STACK Unable to grow stack 

Borland C++ doesn't generate bound instructions that can generate 
SEGV_BOUND-type signals, but they can be used in inline code and 
separately compiled assembler routines that are linked in. 

The following SIGILL-type signals can occur: 

ILL_EXECUTION Illegal operation attempted 

ILL_EXPLICITGEN raise(SIGILL) was executed 

ILL_PRIVILEGED Attempted execution of privileged instruction 

When the signal type is SIGFPE, SIGSEGV, or SIGILL, a return from a 
signal handler is generally not advisable if the state of the 8087 is corrupt, 
the results of an integer division are wrong, an operation that shouldn't 
have overflowed did, a bound instruction failed, or an illegal operation was 
attempted. The only time a return is reasonable is when the handler alters 
the registers so that a reasonable return context exists or the signal type in- 
dicates that the signal was generated explicitly (for example, 
FPE_EXPLICITGEN, SEGV_EXPLICITGEN, or ILL_EXPLICITGEN). 
Generally in this case you would print an error message and terminate the 
program using _exit, exit, or abort . If a return is executed under any other 
conditions, the program's action will probably be unpredictable upon 
resuming. 

Special care must be taken when using the signal function in a multithread 
program. The SIGINT, SIGTERM, and SIGBREAK signals can be used only 
by the main thread (thread one) in a non-PM application. When one of 
these signals occurs, the currently executing thread is suspended, and 
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Return value 



See also 



control transfers to the signal handler (if any) set up by thread one. Other 
signals can be handled by any thread. A signal handler should not use C++ 
run-time library functions, because a semaphore deadlock might occur. 
Instead, the handler should simply set a flag or post a semaphore, and 
return immediately. 

If the call succeeds, signal returns a pointer to the previous handler routine 
for the specified signal type. If the call fails, signal returns SIG_ERR, and the 
external variable errno is set to EINVAL. 

abort, _control87, exit, longjmp, raise, setjmp 



sin, sinl 



math.h 



Function 
Syntax 



Remarks 



sinl 



Return value 
See also 

sinh, sinhl 



Calculates sine. 

double sin(double x) ; 

long double sinl (long double x) ; 
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sin computes the sine of the input value. Angles are specified in radians. 

sinl is the long double version; it takes a long double argument and returns 
a long double result. Error handling for these functions can be modified 
through the functions jnatherr and jnatherrl. 

This function can be used with bed and complex types. 

sin and sinl return the sine of the input value. 

acos, asin, atan, atanl, bed, complex, cos, tan 

math.h 




Function 
Syntax 



sinh 
sinhl 



Calculates hyperbolic sine. 

double sinh(double x) ; 

long double sinhl (long double x) ; 
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sinh, sinhl 



Remarks 



Return value 



See also 



sinh computes the hyperbolic sine, (e x - e" x )/2. 

sinl is the long double version; it takes a long double argument and returns 
a long double result. Error handling for sinh and sinhl can be modified 
through the functions jnatherr and jnatherrl. 

This function can be used with bed and complex types. 

sinh and sinhl return the hyperbolic sine of x. 

When the correct value overflows, these functions return the value 
HUGE_VAL (sinh) or _LHUGE_VAL (sinhl) of appropriate sign. Also, the 
global variable errno is set to ERANGE. 

acos, asin, atan, atan2, bed, complex, cos, cosh, sin, tan, tanh 



sleep 



dos.h 



Function 
Syntax 



Remarks 



Suspends execution for an interval (seconds). 

void sleep (unsigned seconds); 
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Return value 



With a call to sleep, the current program is suspended from execution for 
the number of seconds specified by the argument seconds. The interval is 
accurate only to the nearest hundredth of a second or to the accuracy of the 
operating system clock, whichever is less accurate. 

sleep might return before the specified time period elapses if a signal occurs. 

None. 



sopen 



fcntl.h, sys\stat.h, share.h, io.h 



Function 
Syntax 



Remarks 



Opens a shared file. 

int sopen(char *path, int access, int shflag[, int mode]); 
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sopen opens the file given by path and prepares it for shared reading or 
writing, as determined by access, shflag, and mode. 
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For sopen, access is constructed by ORing flags bitwise from the following 
two lists. Only one flag from the first list can be used; the remaining flags 
can be used in any logical combination. 

List 1 : Read/write flags 

0_RDONLY Open for reading only. 

0_WRONLY Open for writing only. 

0_RDWR Open for reading and writing. 

List 2: Other access flags 



O.NDELAY 
O.APPEND 

O CREAT 



Not used; for UNIX compatibility. 

If set, the file pointer is set to the end of the file prior 

to each write. 

If the file exists, this flag has no effect. If the file does 

not exist, the file is created, and the bits of mode are 

used to set the file attribute bits as in chmod. 

If the file exists, its length is truncated to 0. The file 

attributes remain unchanged. 

Used only with 0_CREAT. If the file already exists, 

an error is returned. 

This flag can be given to explicitly open the file in 

binary mode. 

This flag can be given to explicitly open the file in 

text mode. 

The file is not passed to child programs. 

These 0_. . . symbolic constants are defined in fcntl.h. 

If neither 0_BINARY nor 0_TEXT is given, the file is opened in the transla- 
tion mode set by the global variable Jmode. 

If the 0_CREAT flag is used in constructing access, you need to supply the 
mode argument to sopen from the following symbolic constants defined in 
sys\stat.h. 



O.TRUNC 

0_EXCL 

O.BINARY 

OJTEXT 

O NOINHERIT 



Value of mode 



Access permission 




SJWRITE 

SJREAD 

S_IREAD|S_IWRITE 



Permission to write 
Permission to read 
Permission to read/write 



shflag specifies the type of file-sharing allowed on the file path. Symbolic 
constants for shflag are defined in share.h. 



Value of shflag 



What it does 



SH_C0MPAT 
SH DENYRW 



Identical to SH_DENYNONE 
Denies read/write access. 
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Return value 



See also 



SH_DENYWR 
SH_DENYRD 
SH_DENYNONE 
SH DENYNO 



Denies write access. 
Denies read access. 
Permits read/write access. 
Permits read/write access. 



On successful completion, sopen returns a nonnegative integer (the file 
handle), and the file pointer (that marks the current position in the file) is 
set to the beginning of the file. On error, it returns -1, and the global 
variable errno is set to 

EACCES Permission denied 

EINVACC Invalid access code 

EMFILE Too many open files 

ENOENT Path or file function not found 

chmod, close, creat, lock, Iseek, _rtl_open, open, unlock, umask 



spawnl, spawnle, spawnlp, spawnlpe, spawnv, spawnve, spawnvp, 
spawnvpe process.h, stdio.h 



Function 
Syntax 



The last string must 

be NULL in functions 

spawnle, spawnlpe, 

spawnv, spawnve, 

spawnvp, and 

spawnvpe. 



Remarks 



Creates and runs child processes. 

int spawnl (int mode, char *path, char *argO, argl, ... 
int spawnle(int mode, char '*path, char *argO, argl, ., 
int spawnlp(int mode, char *path, char *argO, argl, .. 
int spawnlpe (int mode, char *path, char *argO, argl, , 

char *envp[] ) ; 
int spawnv(int mode, char *path, char *argv[]); 
int spawnve(int mode, char *path, char *argv[], char i 
int spawnvp(int mode, char *path, char *argv[]); 
int spawnvpe(int mode, char *path, char *argv[], char 



argn, NULL) ; 
, argn, NULL, char 
, argn, NULL) ; 
. , argn, NULL, 



envp[ 



''envpl 



*envp| 
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The functions in the spawn.. . family create child processes that run 
(execute) their own files. There must be sufficient memory available for 
loading and executing a child process. 

The value of mode determines what action the calling function (the parent 
process) takes after the spawn. . . call. The possible values of mode are 

P_WAIT Puts parent process "on hold" until child process 

completes execution. 
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P_NOWAIT Continues to run parent process while child process 

runs. The child process ID is returned, so that the 
parent can wait for completion using cwait or wait. 

P_NOWAITO Identical to P_NOWAIT except that the child process 
ID isn't saved by the operating system, so the parent 
process can't wait for it using cwait or wait. 

P_DETACH Identical to P_NOWAITO, except that the child 

process is executed in the background with no access 
to the keyboard or the display. 

P_OVERLAY Overlays child process in memory location formerly 

occupied by parent. Same as an exec. . . call. 

path is the file name of the called child process. The spawn.. . function calls 
search for path using the standard operating system search algorithm: 

■ If no explicit extension is given, the functions search for the file as given. 
If the file is not found, they add .EXE and search again. If not found, they 
add .CMD and search again. If still not found, they add .BAT and search 
once more. The command processor (CMD.EXE) is used to run the 
executable file. 

h If an extension is given, they search only for the exact file name. 

■ If only a period is given, they search only for the file name with no 
extension. 

■ If path does not contain an explicit directory, spawn. . . functions that have 
the p suffix search the current directory, then the directories set with the 
operating system PATH environment variable. 

The suffixes p, I, and v, and e added to the spawn.. . "family name" specify 
that the named function operates with certain capabilities. 

p The function searches for the file in those directories specified by the 
PATH environment variable. Without the p suffix, the function 
searches only the current working directory. 

I The argument pointers argO, argl, ..., argn are passed as separate 
arguments. Typically, the / suffix is used when you know in advance 
the number of arguments to be passed. 

v The argument pointers argv[0], ..., arg[n] are passed as an array of 
pointers. Typically, the v suffix is used when a variable number of 
arguments is to be passed. 

e The argument envp can be passed to the child process, letting you 
alter the environment for the child process. Without the e suffix, 
child processes inherit the environment of the parent process. 



I 
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Each function in the spawn.. . family must have one of the two argument- 
specifying suffixes (either / or v). The path search and environment 
inheritance suffixes (p and e) are optional. 

For example, 

■ spawnl takes separate arguments, searches only the current directory for 
the child, and passes on the parent's environment to the child. 

■ spawnvpe takes an array of argument pointers, incorporates PATH in its 
search for the child process, and accepts the envp argument for altering 
the child's environment. 

The spawn. . . functions must pass at least one argument to the child process 
(argO or argvWJ). This argument is, by convention, a copy of path. (Using a 
different value for this th argument won't produce an error.) If you want to 
pass an empty argument list to the child process, then argO or argv[0] must 
be NULL. 

When the / suffix is used, argO usually points to path, and argl, ...., argn 
point to character strings that form the new list of arguments. A mandatory 
null following argn marks the end of the list. 

When the e suffix is used, you pass a list of new environment settings 
through the argument envp. This environment argument is an array of 
character pointers. Each element points to a null-terminated character 
string of the form 

envvar = value 

where envvar is the name of an environment variable, and value is the string 
value to which envvar is set. The last element in envpl] is null. When envp is 
null, the child inherits the parents' environment settings. 

The combined length of argO + argl + ... + argn (or of argv[0] + argv[l] + ... 
+ argvln]), including space characters that separate the arguments, must be 
< 256 bytes. Null-terminators are not counted. 

When a spawn.. . function call is made, any open files remain open in the 
child process. 

Return value On a successful execution, the spawn.. . functions where mode is P_WAIT 

return the child process' exit status (0 for a normal termination). If the child 
specifically calls exit with a nonzero argument, its exit status can be set to a 
nonzero value. If mode is P_NOWAIT or P_NOWAITO, the spawn 
functions return the process ID of the child process. This ID can be passed 
to cwait. 

On error, the spawn. . . functions return -1, and the global variable errno is 
set to one of the following: 
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See also 



EINVAL Invalid argument 

ENOENT Path or file name not found 

ENOEXEC Exec format error 

ENOMEM Not enough memory 

abort, atexit, cwait, _exit, exit, exec..., Jpreset, searchpath, system, wait 



_splitpath 



stdlib.h 



Function 
Syntax 



Remarks 



Splits a full path name into its components. 

void _splitpath (const char *path, char *drive, char *dir, char *name, char *ext) 
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_splitpath takes a file's full path name (path) as a string in the form 

X:\DIR\SUBDIR\NAME.EXT 

and splits path into its four components. It then stores those components in 
the strings pointed to by drive, dir, name, and ext . (All five components must 
be passed, but any of them can be a null, which means the corresponding 
component will be parsed but not stored.) The maximum sizes for these 
strings are given by the constants _MAX_DRIVE _MAX_DIR _MAX_PATH 
_MAX_FNAME and _MAX_EXT) (defined in stdlib.h), and each size 
includes space for the null-terminator. These constants are defined in 
stdlib.h. 



Constant 



String 



MAX PATH 


path 


MAX DRIVE 


drive; includes colon (:) 


MAX_DIR 


dir, includes leading and trailing backslashes (\) 


MAX FNAME 


name 


MAX_EXT 


ext, includes leading dot (.) 
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_splitpath assumes that there is enough space to store each non-null 
component. 

When _splitpath splits path, it treats the punctuation as follows: 

■ drive includes the colon (C:, A:, and so on). 

■ dir includes the leading and trailing backslashes 
(\BC\include\, \source\, and so on). 

■ name includes the file name. 
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Return value 
See also 



■ ext includes the dot preceding the extension (.C, .EXE, and so on). 

jnakepath and jsplitpath are invertible; if you split a given path with 
_splitpath, then merge the resultant components with jnakepath, you end up 
with path. 

None. 

Jnllpath, jnakepath 



sprintf 



stdio.h 



Function 
Syntax 



Remarks 



Writes formatted output to a string. 

int sprintf (char *buffer, const char * format [, argument, 
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See printfior details 
on format specifiers. 



Return value 



See also 



sprintf accepts a series of arguments, applies to each a format specifier 
contained in the format string pointed to by format, and outputs the 
formatted data to a string. 

sprintf applies the first format specifier to the first argument, the second to 
the second, and so on. There must be the same number of format specifiers 
as arguments. 

sprintf returns the number of bytes output, sprintf does not include the 
terminating null byte in the count. In the event of error, sprintf returns EOF. 

fprintf, printf 



sqrt, sqrtl 



math.h 



Function 
Syntax 



Remarks 



sqrt 
sqrtl 



Calculates the positive square root. 

double sqrt (double x) ; 

long double sqrtl(long double x) ; 
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sqrt calculates the positive square root of the argument x. 
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Return value 



See also 



sqrtl is the long double version; it takes a long double argument and returns 
a long double result. Error handling for these functions can be modified 
through the functions jnatherr and jnatherrl. 

This function can be used with bed and complex types. 

On success, sqrt and sqrtl return the value calculated, the square root of x. If 
x is real and positive, the result is positive. If x is real and negative, the 
global variable errno is set to 

EDOM Domain error 

bed, complex, exp, log, pow 



srand 



stdlib.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Initializes random number generator. 

void srand (unsigned seed); 
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The random number generator is reinitialized by calling srand with an 
argument value of 1. It can be set to a new starting point by calling srand 
with a given seed number. 

None. 

rand, random, randomize 



sscanf 



stdio.h 




Function 
Syntax 



Remarks 



Scans and formats input from a string. 

int sscanf (const char *buffer, const char * format [, address, 
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sscanf scans a series of input fields, one character at a time, reading from a 
string. Then each field is formatted according to a format specifier passed 
See scant for details on to sscanf 'in the format string pointed to by format. Finally, sscanf stores the 
orma speci ters. formatted input at an address passed to it as an argument following format. 
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Return value 



See also 



There must be the same number of format specifiers and addresses as there 
are input fields. 

sscanf might stop scanning a particular field before it reaches the normal 
end-of-field (whitespace) character, or it might terminate entirely, for a 
number of reasons. See scanf for a discussion of possible causes. 

This function should not be used in PM applications. 

sscanf returns the number of input fields successfully scanned, converted, 
and stored; the return value does not include scanned fields that were not 
stored. If no fields were stored, the return value is 0. 

If sscanf attempts to read at end-of-string, the return value is EOF. 

fscanf scanf 



stackavail 



malloc.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Gets the amount of available stack memory. 

size_t stackavail (void) ; 
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stackavail returns the number of bytes available on the stack. This is the 
amount of dynamic memory that alloca can access. 

stackavail returns a size J value indicating the number of bytes available. 

alloca 



stat 



Seefstat. 



status87 



float.h 



Function 
Syntax 



Gets floating-point status. 

unsigned int _status87 (void) 



194 



Borland C++ for OS/2 Library Reference 



status87 



Remarks 



Return value 
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_status87 gets the floating-point status word, which is a combination of the 
80x87 status word and other conditions detected by the 80x87 exception 
handler. 

The bits in the return value give the floating-point status. See float.h for a 
complete definition of the bits returned by _status87. 



stime 



time.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Sets system date and time. 

int stime (time_t *tp) ; 
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stime sets the system time and date, tp points to the value of the time as 
measured in seconds from 00:00:00 GMT, January 1, 1970. 

stime returns a value of 0. 

asctime,ftime, gettime, gmtime, localtime, time, tzset 



stpcpy 



string.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Copies one string into another. 

char *stpcpy(char *dest, const char *src); 
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stpcpy copies the string src to dest, stopping after the terminating null 
character of src has been reached. 

stpcpy returns dest + strlen(src). 

strcpy 
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strcat 

Function 
Syntax 



Remarks 
Return value 



string.h 



Appends one string to another. 

char *strcat(char *dest, const char *src); 
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strcat appends a copy of src to the end of dest . The length of the resulting 
string is strlen(dest) + strlen(src). 

strcat returns a pointer to the concatenated strings. 



strchr 



string.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Scans a string for the first occurrence of a given character. 

char *strchr (const char *s, int c); 

const char *strchr(const char *s, int c) ; 
char *strchr( char *s, int c); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


" 


■ 


■ 


■ 


■ 



/* C only */ 

// C++ only 
// C++ only 



strchr scans a string in the forward direction, looking for a specific 
character, strchr finds the first occurrence of the character c in the string s. 
The null-terminator is considered to be part of the string, so that, for 
example, 

strchr (strs,0) 

returns a pointer to the terminating null character of the string strs. 

strchr returns a pointer to the first occurrence of the character c in s; if c does 
not occur in s, strchr returns null. 



strcspn, strrchr 
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strchr 



strcmp 

Function 
Syntax 



Remarks 



Return value 



string.h 



Compares one string to another. 

int strcmp(const char *sl, const char *s2); 
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See also 



strcmp performs an unsigned comparison of si to s2, starting with the first 
character in each string and continuing with subsequent characters until 
the corresponding characters differ or until the end of the strings is 
reached. 

strcmp returns a value that is 

■ < if slis less than s2 

■ == if si is the same as s2 

■ > if si is greater than s2 

strcmpi, strcoll, stricmp, strncmp, strncmpi, strnicmp 



strcmpi 



string.h 



Function 
Syntax 



Remarks 



Return value 



Compares one string to another, without case sensitivity. 

int strcmpi(const char *sl, const char *s2); 
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strcmpi performs an unsigned comparison of si to s2, without case 
sensitivity (same as stricmp — implemented as a macro). 

It returns a value (< 0, 0, or > 0) based on the result of comparing si (or part 
of it) to s2 (or part of it). 

The routine strcmpi is the same as stricmp. strcmpi is implemented through a 
macro in string.h and translates calls from strcmpi to stricmp. Therefore, to 
use strcmpi, you must include the header file string.h for the macro to be 
available. This macro is provided for compatibility with other C compilers. 

strcmpi returns an int value that is 
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strcmpi 



See also 



■ < if si is less than s2 

■ == if si is the same as s2 

■ > if si is greater than s2 

strcmp, strcoll, stricmp, strncmp, strncmpi, strnicmp 



strcoll 



string.h 



Function 
Syntax 



Remarks 
Return value 



See also 



Compares two strings. 

int strcoll (char *sl, char *s2) 
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strcoll compares the string pointed to by si to the string pointed to by s2, 
according to the current locale's LC_COLLATE category. 

strcoll returns a value that is 

■ < if si is less than s2 

■ == if si is the same as s2 
m > if si is greater than s2 

strcmp, strcmpi, stricmp, strncmp, strncmpi, strnicmp, strxfrm 



strcpy 



string.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Copies one string into another. 

char *strcpy(char *dest, const char *src); 
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Copies string src to dest, stopping after the terminating null character has 
been moved. 

strcpy returns dest . 

stpcpy 
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strcspn 

Function 
Syntax 



Remarks 

Return value 
See also 



string.h 

Scans a string for the initial segment not containing any subset of a given 
set of characters. 

size_t strcspn(const char *sl, const char *s2); 
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The strcspn functions search s2 until any one of the characters contained in 
si is found. The number of characters which were read in s2 is the return 
value. The string termination character is not counted. Neither string is 
altered during the search. 

strcspn returns the length of the initial segment of string si that consists 
entirely of characters not from string s2. 

strchr, strrchr 



strdate 



time.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Converts current date to string. 

char *_strdate(char *buf); 
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_strdate converts the current date to a string, storing the string in the buffer 
buf. The buffer must be at least 9 characters long. 

The string has the form MM/DD/YY where MM, DD, and YY are all two-digit 
numbers representing the month, day, and year. The string is terminated by 
a null character. 

_strdate returns buf, the address of the date string. 

asctime, ctime, localtime, strftime, _strtime, time 
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strdup 



string.h 



Function 
Syntax 



Copies a string into a newly created location. 

char * strdup (const char *s); 
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strdup 



Remarks 

Return value 
See also 
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strdup makes a duplicate of string s, obtaining space with a call to malloc. 
The allocated space is (strlen(s) + 1) bytes long. The user is responsible for 
freeing the space allocated by strdup when it is no longer needed. 

strdup returns a pointer to the storage location containing the duplicated 
string, or returns null if space could not be allocated. 

free 



strerror 



string.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Builds a customized error message. 

char *_strerror (const char *s); 
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_strerror lets you generate customized error messages; it returns a pointer 
to a null-terminated string containing an error message. 

■ If s is null, the return value points to the most recent error message. 

■ If s is not null, the return value contains s (your customized error 
message), a colon, a space, the most-recently generated system error 
message, and a new line, s should be 94 characters or less. 

_strerror returns a pointer to a constructed error string. The error message 
string is constructed in a static buffer that is overwritten with each call to 
_str error. 

perror, strerror 



strerror 



string.h 



Function 
Syntax 



Returns a pointer to an error message string. 

char *strerror(int errnum) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


' 


■ 


■ 


■ 



200 



Borland C++ for OS/2 Library Reference 



strerror 



Remarks 
Return value 

See also 



strerror takes an int parameter errnum, an error number, and returns a 
pointer to an error message string associated with errnum. 

strerror returns a pointer to a constructed error string. The error message 
string is constructed in a static buffer that is overwritten with each call to 
strerror. 

perror, _strerror 



strftime 



time.h 



Function 
Syntax 



Remarks 



Formats time for output. 

size_t strftime (char *s, size_t maxsize, const char *fmt, const struct tm *t) 
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strftime formats the time in the argument t into the array pointed to by the 
argument s according to the fmt specifications. The format string consists of 
zero or more directives and ordinary characters. Like printf, a directive 
consists of the % character followed by a character that determines the 
substitution that is to take place. All ordinary characters are copied 
unchanged. No more than maxsize characters are placed in s. 

The time is formatted according to the current locale's LCJTIME category. 

The following table describes the ANSI-defined format specifiers. 



Format specifier 


Substitutes 


%% 


Character % 


%a 


Abbreviated weekday name 


%A 


Full weekday name 


%b 


Abbreviated month name 


%B 


Full month name 


%c 


Date and time 


%d 


Two-digit day of the month (01 to 31) 


%H 


Two-digit hour (00 to 23) 


%l 


Two-digit hour (01 to 12) 


%j 


Three-digit day of the year (001 to 366) 


%m 


Two-digit month as a decimal number (1-12) 


%M 


Two-digit minute (00 to 59) 


%p 


AMorPM 


%S 


Two-digit second (00 to 59) 
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%u 


Two-digit week number where Sunday is the first day of the week (00 




to 52) 


%w 


Weekday where is Sunday (0 to 6) 


%W 


Two-digit week number where Monday is the first day of the week (00 




to 52) 


%x 


Date 


%X 


Time 


%y 


Two-digit year without century (00 to 99) 


%Y 


Year with century 


%Z 


Time zone name, or no characters if no time zone 



In addition to the ANSI C-defined format descriptors, the following 
POSIX-defined descriptors are also supported. Each format specifier begins 
with the percent character (%). 



Format specifier 



Substitutes 



You must define 

__USELOCALES__ 

in order to use these 

descriptors. 



%C 
%D 
%e 

%h 
%n 
%r 
%t 
%T 
%u 



Century as a decimal number (00-99). For example, 1992 => 19 

Date in the format mm/dd/yy 

Day of the month as a decimal number in a two-digit field with leading 

space (1-31) 

A synonym for %b 

Newline character 

12-hour time (01-12) format with am/pm string i.e. "%I:%M:%S %p" 

Tab character 

24-hour time (00-23) in the format "HH:MM:SS" 

Weekday as a decimal number (1 Monday - 7 Sunday) 



In addition to these descriptors, strftime also supports the descriptor modi- 
fiers as defined by POSIX on the following descriptors: 



Descriptor modifier Substitutes 



You must define 

__USELOCALES__ 

in order to use these 

descriptors. 



%Od Day of the month using alternate numeric symbols 

%Oe Day of the month using alternate numeric symbols 

%OH Hour (24 hour) using alternate numeric symbols 

%OI Hour (1 2 hour) using alternate numeric symbols 

%Om Month using alternate numeric symbols 

%OM Minutes using alternate numeric symbols 

%OS Seconds using alternate numeric symbols 

%Ou Weekday as a number using alternate numeric symbols 

%OU Week number of the year using alternate numeric symbols 

%Ow Weekday as number using alternate numeric symbols 

%OW Week number of the year using alternate numeric symbols 

%Oy Year (offset from %C) using alternate numeric symbols 



%0 modifier - when this modifier is used before any of the above sup- 
ported numeric format descriptors, for example %Od, the numeric value is 
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Return value 
See also 



converted to the corresponding ordinal string, if it exists. If an ordinal 
string does not exist then the basic format descriptor is used unmodified. 

For example, on 8/20/88 a %d format descriptor would produce 20 but 
%Od on the same day would produce 20 th . 

strftime returns the number of characters placed into s. If the number of 
characters required is greater than maxsize, strftime returns 0. 

localtime, mktime, time 



stricmp 



string.h 



Function 
Syntax 



Remarks 



Return value 



Compares one string to another, without case sensitivity. 

int stricmp (const char *sl, const char *s2); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



See also 



stricmp performs an unsigned comparison of si to s2, starting with the first 
character in each string and continuing with subsequent characters until 
the corresponding characters differ or until the end of the strings is 
reached. The comparison is not case sensitive. 

It returns a value (< 0, 0, or > 0) based on the result of comparing si (or part 
of it) to s2 (or part of it). 

The routines stricmp and strcmpi are the same; strcmpi is implemented 
through a macro in string.h that translates calls from strcmpi to stricmp. 
Therefore, in order to use strcmpi, you must include the header file string.h 
for the macro to be available. 

stricmp returns an int value that is 

b < if si is less than s2 
■ == if si is the same as s2 
a > if si is greater than s2 

strcmp, strcmpi, strcoll, strncmp, strncmpi, strnicmp 




strlen 



string.h 



Function 
Syntax 



Calculates the length of a string. 

size_t strlen(const char *s); 



Chapter 2, Run-time functions 



203 



strlen 



Remarks 
Return value 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


" 


■ 


■ 


■ 


■ 


■ 


■ 



strlen calculates the length of s. 

strlen returns the number of characters in s, not counting the null- 
terminating character. 



strlwr 



string.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Converts uppercase letters in a string to lowercase. 

char *strlwr(char *s); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


" 


" 



strlwr converts uppercase letters in string s to lowercase according to the 
current locale's LC_CTYPE category. For the C locale, the conversion is 
from uppercase letters (A to Z) to lowercase letters (a to z). No other charac- 
ters are changed. 

strlwr returns a pointer to the string s. 

strupr 



strncat 



string.h 



Function 
Syntax 



Remarks 



Return value 



Appends a portion of one string to another. 

char *strncat (char *dest, const char *src, size_t maxlen) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



strncat copies at most maxlen characters of src to the end of dest and then 
appends a null character. The maximum length of the resulting string is 

strlen{dest) + maxlen. 

strncat returns dest. 
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strncmp 

Function 
Syntax 



Remarks 



Return value 



string.h 



Compares a portion of one string to a portion of another. 

int strncmp (const char *sl, const char *s2, size_t maxlen) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



See also 



strncmp makes the same unsigned comparison as strcmp, but looks at no 
more than maxlen characters. It starts with the first character in each string 
and continues with subsequent characters until the corresponding charac- 
ters differ or until it has examined maxlen characters. 

strncmp returns an int value based on the result of comparing si (or part of 
it) to s2 (or part of it): 

■ < if si is less than s2 
b == if si is the same as s2 
b > if si is greater than s2 

strcmp, strcoll, stricmp, strncmpi, strnicmp 



strncmpi 



string.h 



Function 
Syntax 

Remarks 



Compares a portion of one string to a portion of another, without case 
sensitivity. 

int strncmpi (const char *sl, const char *s2, size_t n) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 








■ 




strncmpi performs a signed comparison of si to s2, for a maximum length of 
n bytes, starting with the first character in each string and continuing with 
subsequent characters until the corresponding characters differ or until n 
characters have been examined. The comparison is not case sensitive. 
(strncmpi is the same as strnicmp — implemented as a macro). It returns a 
value (< 0, 0, or > 0) based on the result of comparing si (or part of it) to s2 
(or part of it). 

The routines strnicmp and strncmpi are the same; strncmpi is implemented 
through a macro in string.h that translates calls from strncmpi to strnicmp. 
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strncmpi 



Return value 



Therefore, in order to use strncmpi, you must include the header file 
string.h for the macro to be available. This macro is provided for compati- 
bility with other C compilers. 

strncmpi returns an int value that is 

■ < if si is less than s2 
u == if si is the same as s2 
m > if si is greater than s2 



strncpy 



string.h 



Function 
Syntax 

Remarks 
Return value 



Copies a given number of bytes from one string into another, truncating or 
padding as necessary. 

char * strncpy (char *dest, const char *src, size_t maxlen); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


• 


■ 


■ 


■ 


■ 


■ 



strncpy copies up to maxlen characters from src into dest, truncating or null- 
padding dest . The target string, dest, might not be null-terminated if the 
length of src is maxlen or more. 

strncpy returns dest . 



strnicmp 



string.h 



Function 
Syntax 

Remarks 



Return value 



Compares a portion of one string to a portion of another, without case 
sensitivity. 

int strnicmp (const char *sl, const char *s2, size_t maxlen); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



strnicmp performs a signed comparison of si to s2, for a maximum length of 
maxlen bytes, starting with the first character in each string and continuing 
with subsequent characters until the corresponding characters differ or 
until the end of the strings is reached. The comparison is not case sensitive. 

It returns a value (< 0, 0, or > 0) based on the result of comparing si (or part 
of it) to s2 (or part of it). 

strnicmp returns an int value that is 
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< if si is less than s2 
== if si is the same as s2 
> if si is greater than s2 



strnset 



string.h 



Function 
Syntax 



Remarks 



Return value 



Sets a specified number of characters in a string to a given character. 

char *strnset (char *s, int ch, size_t n) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



strnset copies the character ch into the first n bytes of the string s. If 

n > strlen(s), then strlen{s) replaces n. It stops when n characters have been 

set, or when a null character is found. 

strnset returns s. 



strpbrk 



string.h 



Function 
Syntax 



Remarks 
Return value 



Scans a string for the first occurrence of any character from a given set. 



char *strpbrk( const char *sl, const char *s2); 

const char * strpbrk (const char *sl, const char *s2); 
char *strpbrk(char *sl, const char *s2); 



/* C only */ 

// C++ only 
// C++ only 



strpbrk scans a string, si, for the first occurrence of any character appearing 
in s2. 

strpbrk returns a pointer to the first occurrence of any of the characters in s2. 
If none of the s2 characters occur in si, strpbrk returns null. 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 




strrchr 



string.h 



Function 
Syntax 



Scans a string for the last occurrence of a given character. 

char *strrchr (const char *s, int c) ; 



/* C only */ 
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strrchr 



Remarks 

Return value 
See also 



const char *strrchr (const char *s, int c); 
char *strrchr (char *s, int c) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



// C++ only 
// C++ only 



strrchr scans a string in the reverse direction, looking for a specific 
character, strrchr finds the last occurrence of the character c in the string s. 
The null-terminator is considered to be part of the string. 

strrchr returns a pointer to the last occurrence of the character c. If c does 
not occur in s, strrchr returns null. 

strcspn, strchr 



strrev 



string.h 



Function 
Syntax 



Remarks 



Return value 



Reverses a string. 

char *strrev(char *s); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



strrev changes all characters in a string to reverse order, except the 
terminating null character. (For example, it would change string\0 to 
gnirts\0.) 

strrev returns a pointer to the reversed string. 



strset 



string.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Sets all characters in a string to a given character. 

char *strset(char *s, int ch) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



strset sets all characters in the string s to the character ch. It quits when the 
terminating null character is found. 



strset returns s. 
setmem 
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strspn 

Function 
Syntax 

Remarks 
Return value 



string.h 



Scans a string for the first segment that is a subset of a given set of 
characters. 

size_t strspn(const char *sl, const char *s2); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



strspn finds the initial segment of string si that consists entirely of 
characters from string s2. 

strspn returns the length of the initial segment of si that consists entirely of 
characters from s2. 



strstr 



string.h 



Function 
Syntax 



Remarks 
Return value 



strtime 



Scans a string for the occurrence of a given substring. 

char *strstr(const char *sl, const char *s2); 

const char *strstr (const char *sl, const char *s2); 
char *strstr(char *sl, const char *s2); 



/* C only */ 

// C++ only 
// C++ only 



strstr scans si for the first occurrence of the substring s2. 

strstr returns a pointer to the element in si, where s2 begins (points to s2 in 
si). If s2 does not occur in si, strstr returns null. 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



time.h 




Function 
Syntax 



Remarks 



Converts current time to string. 

char *_strtime(char *buf ) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



_strtime converts the current time to a string, storing the string in the buffer 
buf. The buffer must be at least 9 characters long. 
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strtime 



Return value 
See also 



The string has the following form: 

HH:MM:SS 

where HH, MM, and SS are all two-digit numbers representing the hour, 
minute, and second, respectively. The string is terminated by a null 
character. 

_strtime returns buf, the address of the time string. 

asctime, ctime, localtime, strftime, _strdate, time 



strtod, _strtold 



stdlib.h 



Function 
Syntax 



strtod 
strtold 



Remarks 



Convert a string to a double or long double value. 

double strtod (const char *s, char **endptr); 

long double _strtold (const char *s, char **endptr) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


- 


■ 




■ 


■ 






■ 



strtod converts a character string, s, to a double value, s is a sequence of 
characters that can be interpreted as a double value; the characters must 
match this generic format: 



[ws] [sn] [ddd] 
where 



[ddd] [fmt[sn]ddd] 



[ws] = optional whitespace 
[sn] = optional sign (+ or -) 
[ddd] = optional digits 
[fmt] = optional e or E 
[.] = optional decimal point 

strtod also recognizes +INF and -INF for plus and minus infinity, and 
+NAN and -NAN for Not-a-Number. 

For example, here are some character strings that strtod can convert to 
double: 

+ 1231.1981 e-1 
502.85E2 
+ 2010.952 

strtod stops reading the string at the first character that cannot be 
interpreted as an appropriate part of a double value. 
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strtod, strtold 



Return value 



See also 



If endptr is not null, strtod sets *endptr to point to the character that stopped 
the scan (" endptr = Szstopper). endptr is useful for error detection. 

_strtold is the long double version; it converts a string to a long double 

value. 

These functions return the value of s as a double (strtod) or a long double 
(_strtold). In case of overflow, they return plus or minus HUGE_VAL 
(strtod) or _LHUGE_VAL (_strtold). 

atof 



strtok 



string.h 



Function 
Syntax 

Remarks 



Return value 



strtol 



Searches one string for tokens, which are separated by delimiters defined in 
a second string. 



char *strtok(char *sl, const char *s2); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



strtok considers the string si to consist of a sequence of zero or more text 
tokens, separated by spans of one or more characters from the separator 
string s2. 

The first call to strtok returns a pointer to the first character of the first token 
in si and writes a null character into si immediately following the returned 
token. Subsequent calls with null for the first argument will work through 
the string si in this way, until no tokens remain. 

The separator string, s2, can be different from call to call. 

strtok returns a pointer to the token found in si. A NULL pointer is 
returned when there are no more tokens. 



stdlib.h 




Function 
Syntax 



Converts a string to a long value. 

long strtol (const char *s, char **endptr, int radix); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


" 




■ 


■ 


■ 


■ 


■ 
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strtol 



Remarks 



strtol converts a character string, s, to a long integer value, s is a sequence of 
characters that can be interpreted as a long value; the characters must 
match this generic format: 



[ws] [sn] [( 
where 



[x] [ddd] 



[ws] - optional whitespace 
[sn] = optional sign (+ or -) 
[0] = optional zero (0) 
[x] = optional x or X 
[ddd] = optional digits 

strtol stops reading the string at the first character it doesn't recognize. 

If radix is between 2 and 36, the long integer is expressed in base radix. If 
radix is 0, the first few characters of s determine the base of the value being 
converted. 



Return value 
See also 



First 
character 



Second 
character 



String interpreted as 







1-9 



1-7 
xorX 



Octal 

Hexadecimal 

Decimal 



If radix is 1, it is considered to be an invalid value. If radix is less than or 
greater than 36, it is considered to be an invalid value. 

Any invalid value for radix causes the result to be and sets the next 
character pointer *endptr to the starting string pointer. 

If the value in s is meant to be interpreted as octal, any character other than 
to 7 will be unrecognized. 

If the value in s is meant to be interpreted as decimal, any character other 
than to 9 will be unrecognized. 

If the value in s is meant to be interpreted as a number in any other base, 
then only the numerals and letters used to represent numbers in that base 
will be recognized. (For example, if radix equals 5, only to 4 will be 
recognized; if radix equals 20, only to 9 and A to / will be recognized.) 

If endptr is not null, strtol sets *endptr to point to the character that stopped 
the scan (" endptr = &cstopper). 

strtol returns the value of the converted string, or on error. 

atoi, atol, strtoul 
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strtold 



See strtod. 



strtoul 



strtoul 

Function 
Syntax 



Remarks 

Return value 
See also 



stdlib.h 



Converts a string to an unsigned long in the given radix. 

unsigned long strtoul (const char *s, char **endptr, int radix); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 


■ 


■ 


■ 



strtoul operates the same as strtol, except that it converts a string str to an 
unsigned long value (where strtol converts to a long). Refer to the entry for 
strtol for more information. 

strtoul returns the converted value, an unsigned long, or on error. 

atol, strtol 



strupr 



string.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Converts lowercase letters in a string to uppercase. 

char *strupr(char *s); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



strupr converts lowercase letters in string s to uppercase according to the 
current locale's LC_CTYPE category. For the default C locale, the 
conversion is from lowercase letters {a to z) to uppercase letters (A to Z). No 
other characters are changed. 

strupr returns s. 

strlwr 



strxfrm 



string.h 



Function 



Transforms a portion of a string to a specified collation. 
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strxfrm 



Syntax 



Remarks 



size_t strxfrm(char *target, const char *source, size_t n) ; 



Return value 



See also 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 


■ 


■ 


■ 



strxfrm transforms the string pointed to by source into the string target for 
no more than n characters. The transformation is such that if the strcmp 
function is applied to the resulting strings, its return corresponds with the 
return values of the strcoll function. 

No more than n characters, including the terminating null character, are 
copied to target. 

strxfrm transforms a character string into a special string according to the 
current locale's LC_COLLATE category. The special string that is built can 
be compared with another of the same type, byte for byte, to achieve a 
locale-correct collation result. These special strings, which can be thought 
of as keys or tokenized strings, are not compatible across the different 
locales. 

The tokens in the tokenized strings are built from the collation weights 
used by strcoll from the active locale's collation tables. 

Processing stops only after all levels have been processed for the character 
string or the length of the tokenized string is equal to the maxlen 
parameter. 

All redundant tokens are removed from each level's set of tokens. 

The tokenized string buffer must be large enough to contain the resulting 
tokenized string. The length of this buffer depends on the size of the 
character string, the number of collation levels, the rules for each level and 
whether there are any special characters in the character string. Certain 
special characters can cause extra character processing of the string 
resulting in more space requirements. For example, the French character 
"ce" will take double the space for itself because in some locales, it expands 
to two collation weights at each level. Substrings that have substitutions 
will also cause extra space requirements. 

There is no safe formula to determine the required string buffer size, but at 
least (levels * string length) are required. 

Number of characters copied not including the terminating null character. 
If the value returned is greater than or equal to n, the content of target is 
indeterminate. 

strcmp, strcoll, strncpy 
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swab 



swab 

Function 
Syntax 



Remarks 



Return value 



stdlib.h 



Swaps bytes. 

void swab(char *from, char *to, int nbytes) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 






■ 



swab copies nbytes bytes from the from string to the to string. Adjacent even- 
and odd-byte positions are swapped. This is useful for moving data from 
one machine to another machine with a different byte order, nbytes should 
be even. 

None. 



system 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 



Issue an operating system command. 

int system (const char *command) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 




■ 






■ 



system invokes the operating system command processor to execute an op- 
erating system command, batch file, or other program named by the string 
command, from inside an executing C program. 

To be located and executed, the program must be in the current directory or 
in one of the directories listed in the PATH string in the environment. 

The COMSPEC environment variable is used to find the command 
processor program file, so that file need not be in the current directory. 

If command is a NULL pointer, system returns nonzero if a command proces- 
sor is available. 

If command is not a NULL pointer, system returns if the command 
processor was successfully started. 

If an error occurred, a -1 is returned and errno is set to one of the following: 

ENOENT Path or file function not found 

ENOEXEC Exec format error 

ENOMEM Not enough memory 
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system 



See also 



exec. .., _fpreset, searchpath, spawn.. . 



tan, tanl 



math.h 



Function 
Syntax 



Remarks 



Return value 
See also 



tan 
tanl 



Calculates the tangent. 

double tan(double x); 

long double tanl (long double x) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 


■ 




■ 


■ 






i 



tan calculates the tangent. Angles are specified in radians. 

tanl is the long double version; it takes a long double argument and returns 
a long double result. Error handling for these routines can be modified 
through the functions jnatherr and jnatherrl. 

This function can be used with bed and complex types. 

tan and tanl return the tangent of x, sin(x)/cos(x). 

acos, asin, atan, atanl, bed, complex, cos, sin 



tanh, tanhl 



math.h 



Function 
Syntax 



Remarks 



tanh 
tanhl 



Return value 



Calculates the hyperbolic tangent. 

double tanh(double x) ; 

long double tanhl (long double x) ; 
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tanh computes the hyperbolic tangent, sinh(x)/cosh(x). 

tanhl is the long double version; it takes a long double argument and 
returns a long double result. Error handling for these functions can be 
modified through the functions jnatherr and jnatherrl. 

This function can be used with bed and complex types. 

tanh and tanhl return the hyperbolic tangent of x. 
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tanh, tanhl 



See also 

tell 



bed, complex, cos, cosh, sin, sink, tan 



io.h 



Function 
Syntax 



Remarks 
Return value 

See also 



Gets the current position of a file pointer. 

long tell(int handle); 
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tell gets the current position of the file pointer associated with handle and 
expresses it as the number of bytes from the beginning of the file. 

tell returns the current file pointer position. A return of -1 (long) indicates 
an error, and the global variable errno is set to 

EBADF Bad file number 

fgetpos, f seek, f tell, Iseek 



tempnam 



stdio.h 



Function 
Syntax 



Remarks 



Creates a unique file name in specified directory. 

char *tempnam(char *dir, char *prefix) 
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The tempnam function creates a unique file name in arbitrary directories. 
The unique file is not actually created; tempnam only verifies that it does not 
currently exist. It attempts to use the following directories, in the order 
shown, when creating the file name: 

■ The directory specified by the TMP environment variable. 

■ The dir argument to tempnam. 

m The Pjtmpdir definition in stdio.h. If you edit stdio.h and change this 
definition, tempnam will not use the new definition. 

■ The current working directory. 

If any of these directories is NULL, or undefined, or does not exist, it is 
skipped. 



KB 
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tempnam 



Return value 



See also 



The prefix argument specifies the first part of the file name; it cannot be 
longer than 5 characters, and cannot contain a period (.)• A unique file 
name is created by concatenating the directory name, the prefix, and 6 
unique characters. Space for the resulting file name is allocated with malloc; 
when this file name is no longer needed, the caller should call free to free it. 

If you do create a temporary file using the name constructed by tempnam, it 
is your responsibility to delete the file name (for example, with a call to 
remove). It is not deleted automatically, (tmpfile does delete the file name.) 

If tempnam is successful, it returns a pointer to the unique temporary file 
name, which the caller can pass to free when it is no longer needed. 
Otherwise, if tempnam cannot create a unique file name, it returns NULL. 

mktemp, tmpfile, tmpnam 



textattr 



conio.h 



Function 
Syntax 



Remarks 



Sets text attributes. 

void textattr (int newattr) ; 
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textattr lets you set both the foreground and background colors in a single 
call. (Normally, you set the attributes with textcolor and textbackground.) 

This function does not affect any characters currently onscreen; it affects 
only those characters displayed by functions (such as cprintf) performing 
text mode, direct video output after this function is called. 

The color information is encoded in the newattr parameter as follows: 



7 


6 


5 


4 


3 


2 


1 





B 


b 


b 


b 


f 


f 


f 


f 



















In this 8-bit newattr parameter, 

ujfffis the 4-bit foreground color (0 to 15). 
■ bbb is the 3-bit background color (0 to 7). 
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See also 



textattr 



n B is the blink-enable bit. 

If the blink-enable bit is on, the character blinks. This can be accomplished 
by adding the constant BLINK to the attribute. 

If you use the symbolic color constants defined in conio.h for creating text 
attributes with textattr, note the following limitations on the color you 
select for the background: 

o You can select only one of the first eight colors for the background. 

□ You must shift the selected background color left by 4 bits to move it into 
the correct bit positions. 

These symbolic constants are listed in the following table: 

Symbolic Numeric Foreground or 

constant value background? 



BLACK 





Both 


BLUE 


1 


Both 


GREEN 


2 


Both 


CYAN 


3 


Both 


RED 


4 


Both 


MAGENTA 


5 


Both 


BROWN 


6 


Both 


LIGHTGRAY 


7 


Both 


DARKGRAY 


8 


Foreground only 


LIGHTBLUE 


9 


Foreground only 


LIGHTGREEN 


10 


Foreground only 


LIGHTCYAN 


11 


Foreground only 


LIGHTRED 


12 


Foreground only 


LIGHTMAGENTA 


13 


Foreground only 


YELLOW 


14 


Foreground only 


WHITE 


15 


Foreground only 


BLINK 


128 


Foreground only 



This function should not be used in PM applications. 
Return value None. 

gettextinfo, highvideo, lowvideo, normvideo, textbackground, textcolor 



textbackground conio.h 

Function Selects new text background color. 

oymax vo j_^ textbackground (int newcolor) ; 
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textbackground 



Remarks 
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textbackground selects the background color. This function works for 
functions that produce output in text mode directly to the screen, newcolor 
selects the new background color. You can set newcolor to an integer from 
to 7, or to one of the symbolic constants defined in conio.h. If you use 
symbolic constants, you must include conio.h. 

Once you have called textbackground, all subsequent functions using direct 
video output (such as cprintf) will use newcolor. textbackground does not 
affect any characters currently onscreen. 

The following table lists the symbolic constants and the numeric values of 
the allowable colors: 



Return value 
See also 



Symbolic constant 


Numeric value 


BLACK 





BLUE 


1 


GREEN 


2 


CYAN 


3 


RED 


4 


MAGENTA 


5 


BROWN 


6 


LIGHTGRAY 


7 



This function should not be used in PM applications. 

None. 

gettextinfo, textattr, textcolor 



textcolor 



conio.h 



Function 
Syntax 



Remarks 



Selects new character color in text mode. 

void textcolor (int newcolor); 
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textcolor selects the foreground character color. This function works for the 
console output functions, newcolor selects the new foreground color; You 
can set newcolor to an integer as given in the table below, or to one of the 
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textcolor 



symbolic constants defined in conio.h. If you use symbolic constants, you 
must include conio.h. 

Once you have called textcolor, all subsequent functions using direct video 
output (such as cprintf) will use newcolor. textcolor does not affect any 
characters currently onscreen. 

The following table lists the allowable colors (as symbolic constants) and 
their numeric values: 



Symbolic constant 


Numeric value 


BLACK 





BLUE 


1 


GREEN 


2 


CYAN 


3 


RED 


4 


MAGENTA 


5 


BROWN 


6 


LIGHTGRAY 


7 


DARKGRAY 


8 


LIGHTBLUE 


9 


LIGHTGREEN 


10 


LIGHTCYAN 


11 


UGHTRED 


12 


LIGHTMAGENTA 


13 


YELLOW 


14 


WHITE 


15 


BLINK 


128 



You can make the characters blink by adding 128 to the foreground color. 
The predefined constant BLINK exists for this purpose; for example, 

textcolor (CYAN + BLINK); 

ta^ Some monitors do not recognize the intensity signal used to create the eight 
"light" colors (8-15). On such monitors, the light colors are displayed as 
their "dark" equivalents (0-7). Also, systems that do not display in color 
can treat these numbers as shades of one color, special patterns, or special 
attributes (such as underlined, bold, italics, and so on). Exactly what you'll 
see on such systems depends on your hardware. 

b^- This function should not be used in PM applications. 

Return value None. 

See also gettextinfo, highvideo, lowvideo, normvideo, textattr, textbackground 
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textmode 



textmode 

Function 
Syntax 



Remarks 



conio.h 



Return value 
See also 



Puts screen in text mode. 

void textmode (int newmode); 
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textmode selects a specific text mode. 

You can give the text mode (the argument newmode) by using a symbolic 
constant from the enumeration type textjnodes (defined in conio.h). 

The most commonly used textjnodes type constants and the modes they 
specify are given in the following table. Some additional values are defined 
in conio.h. 



Symbolic 




constant 


Text mode 


LASTMODE 


Previous text mode 


BW40 


Black and white, 40 columns 


C40 


Color, 40 columns 


BW80 


Black and white, 80 columns 


C80 


Color, 80 columns 


MONO 


Monochrome, 80 columns 


C4350 


EGA 43-line and VGA 50-line modes 



When textmode is called, the current window is reset to the entire screen, 
and the current text attributes are reset to normal, corresponding to a call to 

normvideo. 

Specifying LASTMODE to textmode causes the most recently selected text 
mode to be reselected. 

textmode should be used only when the screen or window is in text mode 
(presumably to change to a different text mode). This is the only context in 
which textmode should be used. 

This function should not be used in PM applications. 

None. 

gettextinfo, window 
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time 



time 

Function 
Syntax 



Remarks 

Return value 
See also 



time.h 



Gets time of day. 

time_t time(time_t *timer) ; 
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time gives the current time, in seconds, elapsed since 00:00:00 GMT, January 
1, 1970, and stores that value in the location pointed to by timer, provided 
that timer is not a NULL pointer. 

time returns the elapsed time in seconds, as described. 

asctime, dime, dijf time, f time, gettime, gmtime, localtime, settime, stime, tzset 



tmpfile 



stdio.h 



Function 
Syntax 



Remarks 

Return value 
See also 

tmpnam 



Opens a "scratch" file in binary mode. 

FILE *tmpfile(void) ; 
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tmpfile creates a temporary binary file and opens it for update (iv + b). The 
file is automatically removed when it's closed or when your program 
terminates. 

tmpfile returns a pointer to the stream of the temporary file created. If the 
file can't be created, tmpfile returns NULL. 

fopen, tmpnam 



i 



stdio.h 



Function 
Syntax 



Creates a unique file name. 

char * tmpnam (char *s) ; 
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tmpnam 



Remarks 



Return value 
See also 
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tmpnam creates a unique file name, which can safely be used as the name of 
a temporary file, tmpnam generates a different string each time you call it, 
up to TMP_MAX times. TMP_MAX is defined in stdio.h as 65,535. 

The parameter to tmpnam, s, is either null or a pointer to an array of at least 
LJtmpnam characters. LJmpnam is defined in stdio.h. If s is NULL, tmpnam 
leaves the generated temporary file name in an internal static object and 
returns a pointer to that object. If s is not NULL, tmpnam places its result in 
the pointed-to array, which must be at least LJmpnam characters long, and 
returns s. 

If you do create such a temporary file with tmpnam, it is your responsibility 
to delete the file name (for example, with a call to remove). It is not deleted 
automatically, (tmpfile does delete the file name.) 

If s is null, tmpnam returns a pointer to an internal static object. Otherwise, 
tmpnam returns s. 

tmpfile 



toascii 



ctype.h 



Function 
Syntax 



Remarks 
Return value 



Translates characters to ASCII format. 

int toascii (int c) ; 
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toascii is a macro that converts the integer c to ASCII by clearing all but the 
lower 7 bits; this gives a value in the range to 127. 

toascii returns the converted value of c. 



tolower 



ctype.h 



Function 
Syntax 



Translates characters to lowercase. 

int _tolower(int ch) ; 
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tolower 
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Remarks Jolower is a macro that does the same conversion as tolower, except that it 

should be used only when ch is known to be uppercase (A-Z). 

To use Jolower, you must include ctype.h. 

Return value Jolower returns the converted value of ch if it is uppercase; otherwise, the 

result is undefined. 



tolower 



ctype.h 



Function 
Syntax 



Remarks 



Return value 



Translates characters to lowercase. 

int tolower (int ch) ; 
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tolower is a function that converts an integer ch. (in the range EOF to 255) to 
its lowercase value. The function is affected by the current locale's 
LC_CTYPE category. For the default C locale, ch is converted to a lowercase 
letter (a to z, if it was uppercase, A to Z). All others are left unchanged. 

tolower returns the converted value of ch if it is uppercase; it returns all 
others unchanged. 



Joupper 



ctype.h 



Function 
Syntax 



Remarks 



Return value 



Translates characters to uppercase. 

int _toupper(int ch) ; 
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_toupper is a macro that does the same conversion as toupper, except that it 
should be used only when ch is known to be lowercase letter (a to z). 

To use Joupper, you must include ctype.h. 

Joupper returns the converted value of ch if it is lowercase; otherwise, the 
result is undefined. 
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toupper 



toupper 

Function 
Syntax 



Remarks 



Return value 



ctype.h 



Translates characters to uppercase. 

int toupper (int ch) ; 
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toupper is a function that converts an integer ch (in the range EOF to 255) to 
its uppercase value. The function is affected by the current locale's 
LC_CTYPE category. For the default C locale, ch is converted to an upper- 
case letter (A to Z; if it was lowercase, a to z). All others are left unchanged. 

toupper returns the converted value of ch if it is lowercase; it returns all 
others unchanged. 



Jruncate, Jtruncate 



sys\types.h, io.h 



Function 
Syntax 



Remarks 



Return value 



Changes the file size. 

int _ftruncate(int handle, off_t size); 

int _truncate (const char *path, off_t size); 
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Jruncate changes the size of the file referred to by path. Jtruncate changes 
the size of the file referred to by handle, which must be opened for writing. 
These functions can truncate or extend the file, depending on the value of 
size compared to the file's original size. If the file is being extended, these 
functions will append null characters (\0). If the file is being truncated, all 
data beyond the new end-of-file is lost. 

These functions return on success. On error, they return -1 and set errno 
to one of the following values: 



See also 



EACCES 

EADF 

EINVAL 

ENOENT 



chsize 



Permission denied 

Bad file handle {Jtruncate only) 

size is negative 

File does not exist (Jruncate only) 
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tzset 



tzset 

Function 
Syntax 



Remarks 



time.h 



Sets value of global variables _daylight, Jimezone, and Jzname. 

void tzset (void) 
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Return value 



tzset is available on XENIX systems. 

tzset sets the _daylight, Jimezone, and Jzname global variables based on the 
environment variable TZ. The library functions ftime and localtime use these 
global variables to adjust Greenwich Mean Time (GMT) to the local time 
zone. The format of the TZ environment string is: 

TZ = zzz[+/-]d[d] [ill] 

where zzz is a three-character string representing the name of the current 
time zone. All three characters are required. For example, the string "PST" 
could be used to represent pacific standard time. 

[+/-]d[rf] is a required field containing an optionally signed number with 1 
or more digits. This number is the local time zone's difference from GMT in 
hours. Positive numbers adjust westward from GMT. Negative numbers 
adjust eastward from GMT. For example, the number 5 = EST, +8 = PST, 
and -1 = continental Europe. This number is used in the calculation of the 
global variable Jimezone. Jimezone is the difference in seconds between 
GMT and the local time zone. 

Ill is an optional three-character field that represents the local time zone 
daylight saving time. For example, the string "PDT" could be used to 
represent pacific daylight saving time. If this field is present, it causes the 
global variable _daylight to be set nonzero. If this field is absent, _daylight is 
set to zero. 

If the TZ environment string isn't present or isn't in the preceding form, a 
default TZ = "EST5EDT" is presumed for the purposes of assigning values 
to the global variables _daylight, Jimezone, and Jzname. 

The global variable Jzname[0] points to a three-character string with the 
value of the time-zone name from the TZ environment string. Jzname[l] 
points to a three-character string with the value of the daylight saving 
time-zone name from the TZ environment string. If no daylight saving 
name is present, Jzname[l] points to a null string. 

None. 
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tzset 



See also 

ultoa 



asctime, ctime, ftime, gmtime, localtime, stime, time 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Converts an unsigned long to a string. 

char *ultoa (unsigned long value, char *string, int radix); 
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ultoa converts value to a null-terminated string and stores the result in 
string, value is an unsigned long. 

radix specifies the base to be used in converting value; it must be between 2 
and 36, inclusive, ultoa performs no overflow checking, and if value is 
negative and radix equals 10, it does not set the minus sign. 

The space allocated for string must be large enough to hold the returned 
string, including the terminating null character (\0). ultoa can return up to 
33 bytes. 

ultoa returns string. 

itoa, Itoa 



umask 



io.h 



Function 
Syntax 



Remarks 



Sets file read /write permission mask. 

unsigned umask (unsigned mode); 
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The umask function sets the access permission mask used by open and creat. 
Bits that are set in mode will be cleared in the access permission of files 
subsequently created by open and creat. 

The mode can have one of the following values, defined in sys\stat.h: 
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umask 



Return value 
See also 



Value of mode 



SJWRITE 

SJREAD 

S_IREAD|S_IWRITE 



Access permission 



Permission to write 
Permission to read 
Permission to read and write 



The previous value of the mask. There is no error return. 

creat, open 



ungetc 



stdio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Pushes a character back into input stream. 

int ungetc(int c, FILE *stream) ; 
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ungetc pushes the character c back onto the named input stream, which 
must be open for reading. This character will be returned on the next call to 
getc or fread for that stream. One character can be pushed back in all 
situations. A second call to ungetc without a call to getc will force the 
previous character to be forgotten. A call to f flush, fseek, fsetpos, or rewind 
erases all memory of any pushed-back characters. 

On success, ungetc returns the character pushed back; it returns EOF if the 
operation fails. 

fgetc, getc, getchar 



ungetch 



conio.h 



Function 
Syntax 



Remarks 



Pushes a character back to the keyboard buffer. 

int ungetch (int ch) ; 
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ungetch pushes the character ch back to the console, causing ch to be the 
next character read. The ungetch function fails if it is called more than once 
before the next read. 
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ungetch 



Return value 



See also 



ungetch returns the character ch if it is successful. A return value of EOF 
indicates an error. 

This function should not be used in PM applications. 

getch, getche 



unixtodos 



dos.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Converts date and time from UNIX to DOS format. 

void unixtodos (long time, struct date *d, struct time *t); 
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unixtodos converts the UNIX-format time given in time to DOS format and 
fills in the date and time structures pointed to by d and t. 

time must not represent a calendar time earlier than Jan. 1, 1980 00:00:00. 

None. 

dostounix 



unlink 



io.h 



Function 
Syntax 



Remarks 



Return value 



Deletes a file. 

int unlink (const char *filename) ; 
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unlink deletes a file specified by filename. Any drive, path, and file name can 
be used as a filename. Wildcards are not allowed. 

Read-only files cannot be deleted by this call. To remove read-only files, 
first use chmod or _rtl_chmod to change the read-only attribute. 

This function will fail (EACCES) if the file is currently open in any process. 

If your file is open, be sure to close it before unlinking it. 

On successful completion, unlink returns 0. On error, it returns -1 and the 
global variable errno is set to one of the following values: 
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unlink 



See also 



EACCES Permission denied 
ENOENT Path or file name not found 

chmod, remove 



unlock 



io.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Releases file-sharing locks. 

int unlock(int handle, long offset, long length); 
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unlock provides an interface to the operating system file-sharing 
mechanism, unlock removes a lock previously placed with a call to lock. To 
avoid error, all locks must be removed before a file is closed. A program 
must release all locks before completing. 

unlock returns on success, -1 on error. 

lock, locking, sopen 



utime 



utime.h 



Function 
Syntax 



Remarks 



Sets file time and date. 

int utimefchar *path, struct utimbuf *times); 
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utime sets the modification time for the file path. The modification time is 
contained in the utimbuf structure pointed to by times. This structure is 
defined in utime.h, and has the following format: 

struct utimbuf { 

time_t actime; /* access time */ 
time_t modtime; /* modification time */ 
}; 

The FAT file system supports only a modification time; therefore, on FAT 
file systems utime ignores actime and uses only modtime to set the file's 
modification time. 

If times is NULL, the file's modification time is set to the current time. 
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utime 



Return value 



See also 



utime returns if it is successful. Otherwise, it returns -1, and the global 
variable errno is set to one of the following: 

EACCES Permission denied 
EMFILE Too many open files 

ENOENT Path or file name not found 

setftime, stat, time 



va_arg, va_end 5 va_start 



stdarg.h 



Function 
Syntax 



Remarks 



Implement a variable argument list. 

void va_start (va_list ap, lastfix) ; 
type va_arg(va_list ap, type); 
void va_end(va_list ap) ; 
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Some C functions, such as vfprintf and vprintf, take variable argument lists 
in addition to taking a number of fixed (known) parameters. The va_arg, 
va_end, and va_start macros provide a portable way to access these 
argument lists. They are used for stepping through a list of arguments 
when the called function does not know the number and types of the 
arguments being passed. 

The header file stdarg.h declares one type (valisf) and three macros 
(va_start, va_arg, and va_end). 

■ va_list This array holds information needed by va_arg and va_end. When 
a called function takes a variable argument list, it declares a variable ap of 
type vajist. 

■ va_start: This routine (implemented as a macro) sets ap to point to the 
first of the variable arguments being passed to the function. va_start must 
be used before the first call to va_arg or va_end. 

■ va_start takes two parameters: ap and lastfix. {ap is explained under va_list 
in the preceding paragraph; lastfix is the name of the last fixed parameter 
being passed to the called function.) 

■ va_arg: This routine (also implemented as a macro) expands to an 
expression that has the same type and value as the next argument being 
passed (one of the variable arguments). The variable ap to va_arg should 
be the same ap that va_start initialized. 
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va_arg, va_end, va_start 



Return value 
See also 



Because of default promotions, you can't use char, unsigned char, or 
float types with vajirg. 

The first time va_arg is used, it returns the first argument in the list. Each 
successive time va_arg is used, it returns the next argument in the list. It 
does this by first dereferencing ap, and then incrementing ap to point to 
the following item. va_arg uses the type to both perform the dereference 
and to locate the following item. Each successive time va_arg is invoked, 
it modifies ap to point to the next argument in the list. 

■ va_end: This macro helps the called function perform a normal return. 
va_end might modify ap in such a way that it cannot be used unless 
vajstartis recalled. va_end should be called after va_arg has read all the 
arguments; failure to do so might cause strange, undefined behavior in 
your program. 

va_start and va_end return no values; va_arg returns the current argument in 
the list (the one that ap is pointing to). 

v...printf, v...scanf 



vfprintf 



stdio.h 



Function 
Syntax 



Remarks 



See printf for details 
on format specifiers. 



Return value 



Writes formatted output to a stream. 

int vfprintf (FILE *stream, const char *format, va_list arglist); 
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See also 



The v. . .printf functions are known as alternate entry points for the . . .printf 
functions. They behave exactly like their . . .printf counterparts, but they 
accept a pointer to a list of arguments instead of an argument list. 

vfprintf accepts a pointer to a series of arguments, applies to each argument 
a format specifier contained in the format string pointed to by format, and 
outputs the formatted data to a stream. There must be the same number of 
format specifiers as arguments. 

vfprintf returns the number of bytes output. In the event of error, vfprintf 
returns EOF. 

printf, va_arg, va_end, va_start 
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vfscanf 



vfscanf 

Function 
Syntax 



Remarks 



See scant for details 
on format specifiers. 



stdio.h 



Return value 



Scans and formats input from a stream. 

int vfscanf (FILE *stream, const char *format, va_list arglist) 
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See also 



The v. . .scanf functions are known as alternate entry points for the . . .scanf 
functions. They behave exactly like their . . .scanf counterparts, but they 
accept a pointer to a list of arguments instead of an argument list. 

vfscanf scans a series of input fields, one character at a time, reading from a 
stream. Then each field is formatted according to a format specifier passed 
to vfscanf 'in the format string pointed to by format. Finally, vfscanf stores the 
formatted input at an address passed to it as an argument following format. 
There must be the same number of format specifiers and addresses as there 
are input fields. 

vfscanf might stop scanning a particular field before it reaches the normal 
end-of-field (whitespace) character, or it might terminate entirely, for a 
number of reasons. See scanf for a discussion of possible causes. 

vfscanf returns the number of input fields successfully scanned, converted, 
and stored; the return value does not include scanned fields that were not 
stored. If no fields were stored, the return value is 0. 

If vfscanf attempts to read at end-of-file, the return value is EOF. 

f scanf, scanf, va_arg, va_end, va_start 



vprintf 



stdarg.h 



Function 
Syntax 



Remarks 



Writes formatted output to stdout. 

int vprintf (const char *format, va_list arglist); 
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The v. . .printf functions are known as alternate entry points for the . . .printf 
functions. They behave exactly like their . . .printf counterparts, but they 
accept a pointer to a list of arguments instead of an argument list. 
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vprintf 



See pr/'ntf for details vprintf accepts a pointer to a series of arguments, applies to each a format 
on format specifiers. specifier contained in the format string pointed to by format, and outputs 

the formatted data to stdout. There must be the same number of format 

specifiers as arguments. 



Return value 
See also 



This function should not be used in PM applications. 

vprint returns the number of bytes output. In the event of error, vprint 

returns EOF. 

freopen, printf va_arg, va_end, va_start 



vscanf 



stdarg.h 



Function 
Syntax 



Remarks 



See scant for details 
on format specifiers. 



Return value 



Scans and formats input from stdin. 

int vscanf (const char *format, va_list arglist); 
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See also 



The v. . .scanf functions are known as alternate entry points for the . . .scanf 
functions. They behave exactly like their . . .scanf counterparts, but they 
accept a pointer to a list of arguments instead of an argument list. 

vscanf scans a series of input fields, one character at a time, reading from 
stdin. Then each field is formatted according to a format specifier passed to 
vscanf 'in the format string pointed to by format. Finally, vscanf stores the 
formatted input at an address passed to it as an argument following/ormaf. 
There must be the same number of format specifiers and addresses as there 
are input fields. 

vscanf might stop scanning a particular field before it reaches the normal 
end-of-field (whitespace) character, or it might terminate entirely, for a 
number of reasons. See scanf tor a discussion of possible causes. 

This function should not be used in PM applications. 

vscanf returns the number of input fields successfully scanned, converted, 
and stored; the return value does not include scanned fields that were not 
stored. If no fields were stored, the return value is 0. 

If vscanf attempts to read at end-of-file, the return value is EOF. 

freopen, f scanf, scanf, vajzrg, va_end, va_start 
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vsprintf 



vsprintf 

Function 
Syntax 



Remarks 



See printf for details 
on format specifiers. 



Return value 



See also 



stdarg.h 



Writes formatted output to a string. 

int vsprintf (char *buffer, const char *format, va_list arglist) 
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The v. . .-printf functions are known as alternate entry points for the . . .printf 
functions. They behave exactly like their . . .printf counterparts, but they 
accept a pointer to a list of arguments instead of an argument list. 

vsprintf 'accepts a pointer to a series of arguments, applies to each a format 
specifier contained in the format string pointed to by format, and outputs 
the formatted data to a string. There must be the same number of format 
specifiers as arguments. 

vsprintf returns the number of bytes output. In the event of error, vsprintf 
returns EOF. 

printf, va_arg, va_end, va_start 



vsscanf 



stdarg.h 



Function 
Syntax 



Remarks 



See scant for details 
on format specifiers. 



Scans and formats input from a stream. 

int vsscanf (const char *buffer, const char *format, va_list arglist) 
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The v. . .scanf functions are known as alternate entry points for the . ..scanf 
functions. They behave exactly like their . . . sea nf counterparts, but they 
accept a pointer to a list of arguments instead of an argument list. 

vsscanf scans a series of input fields, one character at a time, reading from a 
stream. Then each field is formatted according to a format specifier passed 
to vsscanf 'in the format string pointed to by format. Finally, vsscanf stores the 
formatted input at an address passed to it as an argument following/ormaf. 
There must be the same number of format specifiers and addresses as there 
are input fields. 

vsscanf might stop scanning a particular field before it reaches the normal 
end-of-field (whitespace) character, or it might terminate entirely, for a 
number of reasons. See scanf 'for a discussion of possible causes. 
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vsscanf 



Return value 



See also 



vsscanf returns the number of input fields successfully scanned, converted, 
and stored; the return value does not include scanned fields that were not 
stored. If no fields were stored, the return value is 0. 

If vsscanf attempts to read at end-of-string, the return value is EOF. 

fscanf scanf sscanf, va_arg, va_end, va_start, vfscanf 



wait 



process.h 



Function 
Syntax 



Remarks 



Return value 



Waits for one or more child processes to terminate. 

int wait(int *statloc) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 








■ 






■ 



The wait function waits for one or more child processes to terminate. The 
child processes must be those created by the calling program; wait cannot 
wait for grandchildren (processes spawned by child processes). If statloc is 
not NULL, it points to location where wait will store the termination status. 

If the child process terminated normally (by calling exit, or returning from 
main), the termination status word is defined as follows: 

Bits 0-7 Zero. 

Bits 8-1 5 The least significant byte of the return code from the child 

process. This is the value that is passed to exit, or is returned 
from main. If the child process simply exited from main with- 
out returning a value, this value will be unpredictable. 

If the child process terminated abnormally, the termination status word is 
defined as follows: 

Bits 0-7 Termination information about the child: 



1 

2 

3 

Bits 8-15 Zero. 



Critical error abort. 

Execution fault, protection exception. 

External termination signal. 




When wait returns after a normal child process termination it returns the 
process ID of the child. 

When wait returns after an abnormal child termination it returns -1 to the 
parent and sets errno to EINTR. 
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wait 



See also 



If wait returns without a child process completion it returns a -1 value and 
sets errno to 



ECHILD 

cwait, spawn 



No child process exists 



wcstombs 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 



Converts a wchar_t array into a multibyte string. 

size_t wcstombs (char *s, const wchar_t *pwcs, size_t n) 
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wcstombs converts the type wchar_t elements contained in pwcs into a 
multibyte character string s. The process terminates if either a null character 
or an invalid multibyte character is encountered. 

No more than n bytes are modified. If n number of bytes are processed 
before a null character is reached, the array s is not null terminated. 

The behavior of wcstombs is affected by the setting of LC_CTYPE category 
of the current locale. 

If an invalid multibyte character is encountered, wcstombs returns (size_t) 
-1. Otherwise, the function returns the number of bytes modified, not 
including the terminating code, if any. 



wctomb 



stdlib.h 



Function 
Syntax 



Remarks 



Converts wchar_t code to a multibyte character. 

int wctomb(char *s, wchar_t wc) ; 
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If s is not null, wctomb determines the number of bytes needed to represent 
the multibyte character corresponding to wc (including any change in shift 
state). The multibyte character is stored in s. At most MB_CUR_MAX 
characters are stored. If the value of wc is zero, wctomb is left in the initial 
state. 
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wctomb 



Return value 



The behavior of wctomb is affected by the setting of LC_CTYPE category of 
the current locale. 

If s is a NULL pointer, wctomb returns a nonzero value if multibyte 
character encodings do have state-dependent encodings, and a zero value if 
they do not. 

If s is not a NULL pointer, wctomb returns -1 if the wc value does not 
represent a valid multibyte character. Otherwise, wctomb returns the 
number of bytes that are contained in the multibyte character correspond- 
ing to wc. In no case will the return value be greater than the value of 
MB CUR MAX macro. 



wherex 



conio.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Gives horizontal cursor position within window. 

int wherex (void) ; 
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wherex returns the x-coordinate of the current cursor position (within the 
current text window). 

This function should not be used in PM applications. 

wherex returns an integer in the range 1 to the number of columns in the 
current video mode. 

gettextinfo, gotoxy, wherey 



wherey 



conio.h 



B 



Function 
Syntax 



Remarks 



Gives vertical cursor position within window. 

int wherey (void) ; 
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wherey returns the y-coordinate of the current cursor position (within the 
current text window). 

This function should not be used in PM applications. 
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wherey 



Return value wherey returns an integer in the range 1 to the number of rows in the 

current video mode. 

See also gettextinfo, gotoxy, zvherex 



window 



conio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Defines active text mode window. 

void window(int left, int top, int right, int bottom); 
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window defines a text window onscreen. If the coordinates are in any way 
invalid, the call to window is ignored. 

left and top are the screen coordinates of the upper left corner of the 
window, right and bottom are the screen coordinates of the lower right 
corner. 

The minimum size of the text window is one column by one line. The 
default window is full screen, with the coordinates: 

1/1/QR 

where C is the number of columns in the current video mode, and R is the 
number of rows. 

This function should not be used in PM applications. 

None. 

clreol, clrscr, delline, gettextinfo, gotoxy, insline, puttext, textmode 



write 



io.h 



Remarks 



Obsolete function. See _rtl_write on page 164. 



write 



io.h 



Function 
Syntax 



Writes to a file. 

int write (int handle, void *buf, unsigned len) ; 
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write 



Remarks 



Return value 



See also 
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write writes a buffer of data to the file or device named by the given handle, 
handle is a file handle obtained from a creat, open, dup, or dup2 call. 

This function attempts to write len bytes from the buffer pointed to by buf 
to the file associated with handle. Except when write is used to write to a text 
file, the number of bytes written to the file will be no more than the number 
requested. The maximum number of bytes that write can write is 
UINT_MAX -1, because UINT_MAX is the same as -1, which is the error 
return indicator for write. On text files, when write sees a linefeed (LF) 
character, it outputs a CR/LF pair. UINT_MAX is defined in limits.h. 

If the number of bytes actually written is less than that requested, the 
condition should be considered an error and probably indicates a full disk. 
For disks or disk files, writing always proceeds from the current file 
pointer. For devices, bytes are sent directly to the device. For files opened 
with the 0_APPEND option, the file pointer is positioned to EOF by write 
before writing the data. 

write returns the number of bytes written. A write to a text file does not 
count generated carriage returns. In case of error, write returns -1 and sets 
the global variable errno to one of the following values: 



EACCES 
EBADF 



Permission denied 
Bad file number 



creat, Iseek, open, read, _rtl_write 
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Global variables 



Borland C++ provides you with predefined global variables for many 
common needs, such as dates, times, command-line arguments, and so on. 
This chapter defines and describes them. 



_argc 



dos.h 



Function 
Syntax 



Remarks 



Keeps a count of command-line arguments. 

extern int _argc; 
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_argc has the value of argc passed to main when the program starts. 



_argv 



dos.h 



Function 
Syntax 



Remarks 



An array of pointers to command-line arguments. 

extern char **_argv; 
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_argv points to an array containing the original command-line arguments 
(the elements of argvU) passed to main when the program starts. 



_ctype 



ctype.h 



Function 
Syntax 



An array of character attribute information. 

extern char _ctype[]; 
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_ctype 



Remarks 
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jotype is an array of character attribute information indexed by ASCII value 
+ 1. Each entry is a set of bits describing the character. 

This array is used only by routines affected by the C locale, such as isdigit, 
isprint, and so on. 



daylight 



time.h 



Function 
Syntax 



Remarks 
See also 



Indicates whether daylight saving time adjustments will be made. 

extern int _daylight; 
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_daylight is used by the time and date functions. It is set by the tzset,ftime, 
and localtime functions to 1 for daylight saving time, for standard time. 

timezone 



environ 



dos.h 



Function 
Syntax 



Remarks 



Accesses the operating system environment variables. 

extern char ** environ; 
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_environ is an array of pointers to strings; it is used to access and alter the 
operating system environment variables. Each string is of the form 

envvar = varvalue 

where envvar is the name of an environment variable (such as PATH), and 
varvalue is the string value to which envvar is set (such as C : \BIN; C : \D0S). 
The string varvalue can be empty. 

When a program begins execution, the operating system environment set- 
tings are passed directly to the program. Note that env, the third argument 
to main, is equal to the initial setting of _environ. 
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environ 



See also 



The _environ array can be accessed by getenv; however, the putenv function 
is the only routine that should be used to add, change or delete the _environ 
array entries. This is because modification can resize and relocate the 
process environment array, but _environ is automatically adjusted so that it 
always points to the array. 

getenv, putenv 



errno, _doserrno 5 _sys_errlist, _sys_nerr 



dos.h, errno.h 



Function 
Syntax 



Remarks 



Enable perror to print error messages. 

extern int _doserrno; 
extern int errno; 
extern char **_sys_errlist; 
extern int _sys_nerr; 
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errno, _sys_errlist, and _sys_nerr are used by perror to print error messages 
when certain library routines fail to accomplish their appointed tasks. 
_doserrno is a variable that maps many operating-system error codes to 
errno; however, perror does not use _doserrno directly. See the header files 
winbase.h and winerror.h for the list of operating-system errors. 

o errno: When an error in a math or system call occurs, errno is set to indi- 
cate the type of error. Sometimes errno and _doserrno are equivalent. At 
other times, errno does not contain the actual operating system error 
code, which is contained in _doserrno instead. Still other errors might 
occur that set only errno, not jioserrno. 

d jdoserrno: When an operating-system call results in an error, jioserrno is 
set to the actual operating-system error code, errno is a parallel error 
variable inherited from UNIX. 

m _sys_errlist: To provide more control over message formatting, the array 
of message strings is provided in _sys_errlist. You can use errno as an 
index into the array to find the string corresponding to the error number. 
The string does not include any newline character. 

b _sys_nerr: This variable is defined as the number of error message strings 
in _sys_errlist. 

The following table gives mnemonics and their meanings for the values 
stored in _sys_errlist. The list is alphabetically ordered for easier reading. 
For the numerical ordering, see the header file errno.h. 
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errno, _doserrno, _sys_errlist, _sys_nerr 



Mnemonic 


Meaning 


E2BIG 


Arg list too long 


EACCES 


Permission denied 


EBADF 


Bad file number 


ECHILD 


No child process 


ECONTR 


Memory blocks destroyed 


ECURDIR 


Attempt to remove CurDir 


EDEADLOCK 


Locking violation 


EDOM 


Math argument 


EEXIST 


File already exists 


EFAULT 


Unknown error 


EINTR 


Interrupted function call 


EINVACC 


Invalid access code 


EINVAL 


Invalid argument 


EINVDAT 


Invalid data 


EINVDRV 


Invalid drive specified 


EINVENV 


Invalid environment 


EINVFMT 


Invalid format 


EINVFNC 


Invalid function number 


EINVMEM 


Invalid memory block address 


EIO 


Input/Output error 


EMFILE 


Too many open files 


ENAMETOOLONG 


File name too long 


ENFILE 


Too many open files 


ENMFILE 


No more files 


ENODEV 


No such device 


ENOENT 


No such file or directory 


ENOEXEC 


Exec format error 


ENOFILE 


File not found 


ENOMEM 


Not enough core 


ENOPATH 


Path not found 


ENOSPC 


No space left on device 


ENOTSAM 


Not same device 


ENXIO 


No such device or address 


EPERM 


Operation not permitted 


EPIPE 


Broken pipe 


ERANGE 


Result too large 


EROFS 


Read-only file system 


ESPIPE 


Illegal seek 


EXDEV 


Cross-device link 


EZERO 


Error 
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fileinfo 



Jileinfo 

Function 
Syntax 



Remarks 



stdlib.h 



Passes file information to a child process. 

extern int _fileinfo; 
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The value of Jileinfo determines whether information about open files is 
passed to a child process. By default, the value of Jileinfo is 0. If Jileinfo has 
a nonzero value, file information is passed to child processes. 

Alternatively, child processes can inherit such information about open files 
by linking your program with the object file FILEINFO.OBJ. For example: 

bcc test.c \BC0S2\lib\fileinfo.obj 

The file information is passed in the environment variable _C_FILE_INFO. 
This variable contains encoded binary information, and your program 
should not attempt to read or modify its value. The child program must 
have been built with the C++ run-time library to inherit this information 
correctly. Other programs can ignore _C_FILE_INFO, and will not inherit 
file information. 



floatconvert 



stdio.h 



Function 
Syntax 



Remarks 



Links the floating-point formats. 

extern int _floatconvert; 
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Floating-point output requires linking of conversion routines used by 
printf scanf, and any variants of these functions. To reduce executable size, 
the floating-point formats are not automatically linked. However, this 
linkage is done automatically whenever your program uses a mathematical 
routine or the address is taken of some floating-point number. If neither of 
these actions occur the missing floating-point formats can result in a run- 
time error. 
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fmode 



Jmode 

Function 
Syntax 



Remarks 



fcntl.h 



Determines default file-translation mode. 

extern int _fmode; 
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Jmode determines in which mode (text or binary) files will be opened and 
translated. The value of Jmode is 0_TEXT by default, which specifies that 
files will be read in text mode. If Jmode is set to OJBINARY, the files are 
opened and read in binary mode. (0_TEXT and 0_BINARY are defined in 
fcntl.h.) 

In text mode, carriage-return/linefeed (CR/LF) combinations are translated 
to a single linefeed character (LF) on input. On output, the reverse is true: 
LF characters are translated to CR/LF combinations. 

In binary mode, no such translation occurs. 

You can override the default mode as set by Jmode by specifying a t (for 
text mode) or b (for binary mode) in the argument type in the library 
functions fopen, fdopen, and j reopen. Also, in the function open, the argument 
access can include either 0_BINARY or 0_TEXT, which will explicitly 
define the file being opened (given by the open pathname argument) to be in 
either binary or text mode. 



new handler 



Function 
Syntax 



Remarks 



Traps new allocation miscues. 

typedef void (*pvf)(); 
pvf _new_handler; 

As an alternative, you can set using the function set_newjiandler, like this: 

pvf set_new_handler(pvf p) ; 
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_newjiandler contains a pointer to a function that takes no arguments and 
returns void. If operator new() is unable to allocate the space required, it 
will call the function pointed to by _new Jiandler; if that function returns it 
will try the allocation again. By default, the function pointed to by 
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new handler 



_new_handler terminates the application. The application can replace this 
handler, however, with a function that can try to free up some space. This is 
done by assigning directly to _new_handler or by calling the function 
setjiewjiandler, which returns a pointer to the former handler. 

jnewjiandler is provided primarily for compatibility with C++ version 1.2. 
In most cases this functionality can be better provided by overloading 
operator new(). 



_osmajor, _osminor, _osversion 



dos.h 



Function 
Syntax 



Remarks 



Contain the major and minor operating-system version numbers. 

extern unsigned char _osmajor; 
extern unsigned char _osminor; 
extern unsigned _osversion; 
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The major and minor version numbers are available individually through 
_osmajor and _osminor. _osmajor is the major version number, and _osminor 
is the minor, version number. For example, if you are running OS/2 version 
2.0, _osmajor will be 3 and _osminor will be 20. 

_osversion is functionally identical to jversion. See the discussion of juersion. 



threadid 



stddef.h 



Function 
Syntax 



Remarks 



Pointer to thread ID. 

extern long _threadid; 
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Jhreadid is a long integer that contains the ID of the currently executing 
thread. It is implemented as a macro, and should be declared only by 
including stddef.h. 
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JhrowExceptionName, throwFileName, throwLineNumber 



throwExceptionName, throwFileName, throwLineNumber except.h 



Function 
Syntax 



Remarks 



Generates information about a thrown exception. 

extern char * throwExceptionName; 

extern char * throwFileName; 

extern char * throwLineNumber; 
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Use these global variables to get the name and location of a thrown 
exception. The output for each of the variables is a printable character 
string. 

To get the file name and line number for a thrown exception with 

throwFileName and throwLineNumber, you must compile the module 

with the -xp compiler option. 



timezone 



time.h 



Function 
Syntax 



Remarks 



See also 



Contains difference in seconds between local time and GMT. 

extern long _timezone; 
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_timezone is used by the time-and-date functions. 

This variable is calculated by then tzset function; it is assigned a long value 
that is the difference, in seconds, between the current local time and 
Greenwich mean time. 

_daylight 



tzname 



time.h 



Function 
Syntax 



Array of pointers to time-zone names. 

extern char * _tzname[2] 
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tzname 



Remarks 



The global variable Jtzname is an array of pointers to strings containing 
abbreviations for time-zone names. _tzname[0] points to a three-character 
string with the value of the time-zone name from the TZ environment 
string. The global variable _tzname[l] points to a three-character string with 
the value of the daylight-saving time-zone name from the TZ environment 
string. If no daylight saving name is present, _tzname[l] points to a null 
string. 



version 



dos.h 



Function 
Syntax 



Remarks 



Contains the operating-system version number. 

extern unsigned _version; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


- 




■ 


■ 






■ 



juersion contains the operating-system version number, with the major 
version number in the high byte and the minor version number in the low 
byte. For a 32-bit application, this layout of the version number is in the 
low word. For OS/2 version 2.0, juersion has the value 20 (twenty). 



wscroll 



conio.h 



Function 
Syntax 



Remarks 



Enables or disables scrolling in console I/O functions. 

extern int wscroll 
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jwscroll is a console I/O flag. Its default value is 1. If you set jwscroll to 0, 
scrolling is disabled. This can be useful for drawing along the edges of a 
window without having your screen scroll. 
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The C++ iostreams 



Online help provides 

sample programs for 

many iostream 

classes. 



The stream class library in C++ consists of several classes distributed in two 
separate hierarchical trees. See the Programmer's Guide, Chapter 6, for an 
illustration of the class hierarchies. This reference presents some of the 
most useful details of these classes, in alphabetical order. The following 
cross-reference table tells which classes belong to which header files. 



Table 4.1 

The functions 

declared in 

constrea.h are not 

available for PM 

applications. 



Header file 



constrea.h 
iostream.h 

fstream.h 
strstrea.h 



Classes 



conbuf, constream 

ios, iostream, iostreamjvithassign, istream, istream_withassign, 

ostream, ostream_withassign, streambuf 

filebuf, istream, istreambase, ifstream, ofstream 

istrstream, ostrstream, strstream, strstreambase, strstreambuf 



conbuf class 



constrea.h 



conbuf is not 
available for PM. 



Specializes streambuf to handle console output. 



Public constructor 



Constructor conbuf ( ) 

Makes an unattached conbuf. 

Public member functions 



clreol 



clrscr 



void clreol () 

Clears to end of line in text window. 

void clrscr () 

Clears the defined screen. 
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conbuf class 



delline void dellineO 

Deletes a line in the window. 
gotoxy void gotoxy(int x, int y) 

Positions the cursor in the window at the specified location. 
highvideo void highvideo ( ) 

Selects high-intensity characters. 
insline void inslineO 

Inserts a blank line. 
lOWVideo void lowvideoO 

Selects low-intensity characters. 
normvideo void normvideof) 

Selects normal-intensity characters. 
Overflow virtual int overflow ( int = EOF ) 

Flushes the conbuf to its destination. 
setcursortype void setcursortype(int cur_type) 

Selects the cursor appearance. 
textattr V oid textattr(int newattribute) 

Selects cursor appearance. 
textbackground V oid textbackground(int newcolor) 

Selects the text background color. 
textCOlor V oid textcolor( int newcolor) 

Selects character color in text mode. 
textmode static void textmode(int newmode) 

Puts the screen in text mode. 
Wherex i nt w herex() 

Gets the horizontal cursor position. 
Wherey i nt whereyO 

Gets the vertical cursor position. 
window void window (int left, int top, int right, int bottom) 
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constream class 



Defines the active window. 



constream class 



constrea.h 



constream is not 
available for PM. 



Constructor 



Provides console output streams. This class is derived from ostream. 

Public constructor 

constream () 

Provides an unattached output stream to the console. 



Public member functions 



clrscr 



rdbuf 



textmode 



window 



void clrscr () 

Clears the screen. 

conbuf *rdbuf() 

Returns a pointer to this constream's assigned conbuf. 

void textmode (int newmode) 
Puts the screen in text mode. 

void window (int left, int top, int right, int bottom) 
Defines the active window. 



f ilebuf class 



fstream.h 



Specializes streambuf to use files for input and output of characters. The 
filebuf class manages buffer allocation and deletion, and seeking within a 
file. This class also permits unbuffered file I/O by using the appropriate 
constructor or the member iunction filebuf ::setbuf. By default, files are 
opened in openprot mode to allow reading and writing. See page 261 for a 
list of file-opening modes. 

The filebuf class only provides basic services for file I/O. Input and output 
to a filebuf can only be done with the low-level functions provided by 
streambuf. Higher level classes provide formatting services. 
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filebuf class 



Public constructors 



Constructor 



Constructor 



filebuf (); 

Makes a filebuf that isn't attached to a file. 

filebuf (int fd) ; 

Makes a filebuf attached to a file as specified by file descriptor fd. 

filebuf (int fd, char *buf, int n) ; 

Makes a filebuf attached to a file specified by the file descriptor fd, and uses 
buf as the storage area. The size of buf is sufficient to store n bytes. If buf is 
NULL or n is non-positive, the filebuf is unbuffered. 



Public data members 



openprot 



static const int openprot 

The default file protection. The exact value of openprot should not be of 
interest to the user. Its purpose is to set the file permissions to read and 
write. 



Public member functions 



attach 



close 



fd 



is_open 



filebuf* attach (int fd) 

Connects this closed filebuf to a file specified by the file descriptor fd. If the 
file buffer is already open, attach fails and returns NULL. Otherwise, the file 
buffer is connected to fd. 

filebuf* close)) 

Flushes and closes the file. Generally, it is not necessary to make an explicit 
call to close at your program's end because proper file closing is ensured by 
the filebuf destructor. An explicit call to close is useful when you want to 
disconnect the filebuf from your program. 

Returns on error, for example, if the file was already closed. Otherwise, 
the function returns a reference to the filebuf (the this pointer). 

int fd() 

Returns the file descriptor or EOF. 

int is_open() ; 
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filebuf class 



open 



overflow 



seekoff 



setbuf 



sync 



underflow 



Returns nonzero if the file is open. 

filebuf* open (const char * filename, int mode, 
int prot - filebuf : :openprot) ; 

Opens the file specified by filename and connects to it. The file-opening 
mode is specified by mode. 

virtual int overflow(int c = EOF); 

Flushes a buffer to its destination. Every derived class should define the 
actions to be taken. 

virtual streampos seekoff (streamoff offset, dir ios: :seek_dir, int mode); 

Moves the file get/put pointer an offset number of bytes. The pointer is 
moved in the direction specified by dir relative to the current position, mode 
can specify read (ios::in), write (ioswout), or both. If mode is ioswin, the get 
pointer is adjusted. If mode is ioswout, the put pointer is adjusted. 

If successful, the seekoff function returns a streampos-type value that 
indicates the new file pointer position. 

The function can fail if the file does not support repositioning or you 
request an illegal pointer repositioning, for example, beyond the end of the 
file. On failure, seekoff returns EOF. The file pointer position is undefined. 

virtual streambuf* setbuf (char *buf, int len) ; 

Allocates bufof size len for use by the filebuf. If buf is NULL or len is a non- 
positive value, the filebuf is unbuffered. 

On success, setbuf returns a pointer to the filebuf. A failure occurs if the file 
is open and a buffer has been allocated. On failure, setbuf returns NULL 
and no changes are made to the buffering status. 

virtual int sync ( ) ; 

Establishes consistency between internal data structures and the external 
stream representation. 

virtual int underflow! ); 

Makes input available. This is called when no more data exists in the input 
buffer. Every derived class should define the actions to be taken. 



fstream class 



fstream.h 



This stream class, derived from fstreambase and iostream, provides for 
simultaneous input and output on a. filebuf. 
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fstream class 



Public constructors 



Constructor 



Constructor 



Constructor 



Constructor 



fstream () ; 

Makes an fstream that isn't attached to a file. 

fstream (const char *name, int mode, int prot 



filebuf : :openprot) ; 



Makes an fstream, opens a file with access as specified by mode, and 
connects to it. See page 261 for access options provided by ios::open_mode. 

fstream (int fd) ; 

Makes an fstream and connects to an open-file descriptor specified by fd. 

fstream(int fd, char *buf, int n) ; 

Makes a fstream attached to a file specified by the file descriptor fd, and uses 
buf as the storage area. The size of buf is sufficient to store n bytes. If buf is 
NULL or n is non-positive, the fstream is unbuffered. 

Public member functions 



open 



rdbuf 



void open(const char *name, int mode, int prot = filebuf : ropenprot) ; 

Opens a file specified by name for an fstream. The file-opening mode is 
specified by the variable mode. 

filebuf* rdbuf (); 

Returns the filebuf used. 



fstreambase class 



fstream.h 



This stream class, derived from ios, provides operations common to file 
streams. It serves as a base for fstream, ifstream, and ofstream. 

Public constructors 



Constructor 



Constructor 



fstreambase ( ) ; 

Makes an fstreambase that isn't attached to a file. 

fstreambase (const char *name, int mode, int = filebuf : ropenprot) ; 
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fstreambase class 



Constructor 



Constructor 



attach 

close 

open 

rdbuf 

setbuf 



Makes an fstreambase, opens a file specified by name in mode specified by 
mode, and connects to it. 

fstreambase (int fd) ; 

Makes an fstreambase and connects to an open-file descriptor specified by fd. 

fstreambase (int fd, char *buf, int len); 

Makes an fstreambase connected to an open-file descriptor specified by fd. 
The buffer is specified by buf 'and the buffer size is len. 

Public member functions 

void attach (int fd) ; 

Connects to an open-file descriptor. 

void closed ; 

Closes the associated filebuf and file. 

void open(const char *name, int mode, int prot = filebuf ::openprot) ; 
Opens a file for an fstreambase. The file-opening mode is specified by mode. 
filebuf* rdbuf (); 
Returns the filebuf used. 

void setbuf (char *buf, int len); 

Reserves an area of memory pointed to by buf. The area is sufficiently large 
to store len number of bytes. 



ifstream class 



fstream.h 



This stream class, derived from fstreambase and {stream, provides input 
operations on a filebuf. 

Public constructors 



Constructor 



Constructor 



ifstream () ; 

Makes an ifstream that isn't attached to a file. 

ifstream(const char *name, int mode = ios::in, 
int prot = filebuf : :openprot) ; 
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ifstream class 



Makes an ifstream, opens a file for input in protected mode, and connects to 
it. By default, the file is not created if it does not already exist. 

Constructor ifstream(int fd) ; 

Makes an ifstream and connects to an open-file descriptor fd. 

Constructor ifstream(int fd, char *buf, int buf_len) ; 

Makes an ifstream connected to an open file. The file is specified by its 
descriptor, fd. The ifstream uses the buffer specified by buf of length bufjen. 

Public member functions 



open 
rdbuf 



void open(const char *name, int mode, int prot = filebuf : :openprot) ; 
Opens a file for an ifstream. 
filebuf* rdbuf (); 
Returns the filebuf used. 



ios class 



iostream.h 



Provides operations common to both input and output. Its derived classes 
(istream, ostream, iostream) specialize I/O with high-level formatting 
operations. The ios class is a base for istream, ostream, fstreambase, and 
strstreambase. 

Public data members 

The following three constants are used as the second parameter of the setf 
function: 

static const long adjustfield; // left I right I internal 
static const long basefield; // dec I oct I hex 
static const long floatfield; // scientific I fixed 

Stream seek direction: 

enum seek_dir { beg=0, cur=l, end=2 }; 
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Stream operation mode. These can be logically ORed: 

enum open_mode { 

app, Append data — always write at end of file. 

ate, Seek to end of file upon original open. 

in, Open for input (default for ifstreams). 

out, Open for output (default for of streams). 

binary, Open file in binary mode. 

trunc, Discard contents if file exists (default if out is specified 

and neither ate nor app is specified). 

nocreate, If file does not exist, open fails. 

noreplace, If file exists, open for output fails unless ate or app is set. 



Format flags used with flags, setf, and unsetf member functions: 

enum { 

skipws, Skip whitespace on input. 

left, Left-adjust output. 

right, Right-adjust output. 

internal, Pad after sign or base indicator. 

dec, Decimal conversion. 

oct, Octal conversion. 

hex, Hexadecimal conversion. 

showbase, Show base indicator on output. 

showpoint, Show decimal point for floating-point output. 

uppercase, Uppercase hex output. 

showpos, Show '+' with positive integers. 

scientific, Suffix floating-point numbers with exponential (E) 

notation on output. 

fixed, Use fixed decimal point for floating-point numbers. 

unitbuf, Flush all streams after insertion. 

stdio, Flush stdout, stderr after insertion. 



Protected data members 



streambuf 


*bp; 


int 


x_fill; 


long 


x_flags; 


int 


x_precision 



/ / The associated streambuf 

/ / Padding character of output 

/ / Formatting flag bits 

/ / Floating-point precision on output 
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ios class 



Constructor 



Constructor 



bad 



bitalloc 



clear 



eof 



fail 



fill 



fill 



flags 



int 


state; 


ostream 


*x_tie; 


int 


x_width; 



/ / Current state of the streambuf 
/ / The tied ostream, if any 
// Field width on output 



Public constructor 



ios (streambuf *) ; 

Associates a given streambuf 'with the stream. 

Protected constructor 



ios ( ) ; 

Constructs an ios object that has no corresponding streambuf. 

Public member functions 

int bad ( ) ; 

Nonzero if error occurred. 

static long bitallocO; 

Acquires a new flag bit set. The return value can be used to set, clear, and 
test the flag. This is for user-defined formatting flags. 

void clear (int = 0) ; 

Sets the stream state to the given value. 

int eof () ; 

Nonzero on end of file. 

int fail() ; 

Nonzero if an operation failed. 

char fill() 

Returns the current fill character. 

char fill (char) ; 

Resets the fill character; returns the previous character. 

long flags ( ) ; 

Returns the current format flags. 
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ios class 



flags 

good 

precision 

precision 

rdbuf 

rdstate 
setf 

setf 

sync_with_stdio 
tie 



tie 



unsetf 



long flags (long) ; 

Sets the format flags to be identical to the given long; returns previous 
flags. Use flags(O) to set the default format. 

int good ( ) ; 

Nonzero if no state bits were set (that is, no errors appeared). 

int precision () ; 

Returns the current floating-point precision. 

int precision (int) ; 

Sets the floating-point precision; returns previous setting. 

streambuf* rdbuf () ; 

Returns a pointer to this stream's assigned streambuf. 

int rdstate () ; 

long setf (long) ; 

Sets the flags corresponding to those marked in the given long; returns 
previous settings. 

long setf (long _setbits, long _f ield) ; 

The bits corresponding to those marked in Jield are cleared, and then reset 
to be those marked in _setbits. 

static void sync_with_stdio() ; 

Mixes stdio files and iostreams. This should not be used for new code. 

ostream* tie() ; 

Returns the tied stream, or NULL if there is none. Tied streams are those 
that are connected such that when one is used, the other is affected. For 
example, cin and cout are tied; when cin is used, it flushes cout first. 

ostream* tie(ostream *out); 

Ties another stream to the output stream out and returns the previously 
tied stream. If the stream was not previously tied, tie returns NULL. 

When an input stream has characters to be consumed, or if an output 
stream needs more characters, the tied stream is first flushed automatically. 
By default, cin, cerr and clog are tied to cout. 

long unsetf (long f ) ; 
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Clears the bits corresponding to/ and returns a long that represents the 
previous settings. 

Width i nt width(); 

Returns the current width setting. 
Width i nt width (int); 

Sets the width as given; returns the previous width. 

xai'OC static int xallocO; 

Returns an array index of previously unused words that can be used as 
user-defined formatting flags. 

Protected member functions 

In| t void init (streambuf *); 

Provides the actual initialization. 
setState void setstate (int); 

Sets all status bits. 

iostream class iostream.h 

This class, derived from {stream and ostream, is a mixture of its base classes, 
allowing both input and output on a stream. It is a base for /stream and 
strstream. 

Public constructor 

Constructor iostream (streambuf *); 

Associates a given streambuf 'with the stream. 

iostream_withassign class iostream.h 

This class is an iostream with an added assignment operator. 
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iostream_withassign class 



Public constructor 



Constructor iostream_withassign ( ) ; 

Default constructor (calls iostream's constructor). 

Public member functions 



None (although the = operator is overloaded). 



istream class 



iostream.h 



Provides formatted and unformatted input from a streambuf. The » 
operator is overloaded for all fundamental types, as explained in the 
narrative at the beginning of the chapter. This ios class is a base for ifstream, 
iostream, istrstream, and istream_withassign. 



Public constructor 



Constructor istream (streambuf *); 

Associates a given streambuf 'with the stream. 



Public member functions 



gcount 

get 

get 



int gcount ( ) ; 

Returns the number of characters last extracted. 

int get ( ) ; 

Extracts the next character or EOF. 

istream& get (char *buf, int len, char delim = '\n'); 
istream& get (signed char *buf, int len, char delim = ' \n'); 
istreamk get (unsigned char *buf, int len, char delim = '\n'); 

Extracts characters and stores them in buf until the delimiter, specified by 
delim, or end-of-file is encountered, or until (len - 1) bytes have been read. A 
terminating null is always placed in the output string; the delimiter never 
is. The delimiter remains in the stream. Fails only if no characters were 
extracted. 
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istream class 



get 

get 
getline 



ignore 
ipfx 

peek 

putback 

read 



seekg 
seekg 



The get function fails if it encounters the end of file before any characters 
are stored. On failure, get sets iosv.failbit. 

istreamk get (char &ch) ; 
istreamk get (signed char &ch) ; 
istreamSc get (unsigned char &ch) ; 

Extracts a single character into the ch reference. 

istreamk get (streambuf &sbuf, char delim = '\n'); 

Extracts characters into the given sbuf reference until delim is encountered. 

istream& getline (char *buf, int len, char) ; 

istream& getline (signed char *buf, int len, char delim = '\n'); 

istreamk getline (unsigned char *buf, int len, char delim = '\n'); 

Same as get, except the delimiter is also extracted. Generally, the specified 
delim is not copied to buf However, if the delimiter is encountered exactly 
when len characters have been extracted, delim is not extracted. 

istreamk ignore(int n = 1, int delim = EOF); 

Causes up to n characters in the input stream to be skipped; stops if delim is 
encountered. 

istream& ipfx(int n = 0); 

The ipfx function is called by input functions prior to fetching from an input 
stream. Functions that perform formatted input call ipfx(O); unformatted 
input functions call ipfx(l). 

int peek ( ) ; 

Returns next char without extraction. 

istream& putback (char) ; 

Pushes back a character into the stream. 

istream& read(char*, int); 
istream& read (signed char*, int); 
istreamk read(unsigned char*, int) ; 

Extracts a given number of characters into an array. Use gcount for the 
number of characters actually extracted if an error occurred. 

istream& seekg (streampos pos); 

Moves to an absolute position in the input stream. 

istream& seekg (streamoff offset, seek_dir dir) ; 
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istream class 

Moves offset number of bytes relative to the current position for the input 
stream. The offset is in the direction specified by dir following the 
definition: enum seek_dir {beg, cur, end}; 

Use ostreamv.seekp for positioning in an output stream. 

Use seekpos or seekoffiox positioning in a stream buffer. 

tel'9 streampos tellgO; 

Returns the current stream position. On failure, tellg returns a negative 
number. 

Use ostreamv.tellp to find the position in an output stream. 

Protected member functions 

eatwhite void eatwhite ( ) ; 

Extract consecutive whitespace. 

istream_withassign class iostream.h 

This class is an istream with an added assignment operator. 

Public constructor 

Constructor istream_withassign ( ) ; 

Default constructor (calls {stream's constructor). 

Public member functions 

None (although the = operator is overloaded). 

istrstream class strstrea.h 

Provides input operations on a strstreambuf. This class is derived from 
strstreambase and istream. 
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Public constructors 



Constructor istrstream (char *); 

istrstream (signed char *); 
istrstream (unsigned char *); 

Each of the constructors above makes an istrstream with a specified string (a 
null character is never extracted). See "The three char types" in Chapter 1 
of the Programmer's Guide for a discussion of character types. 

Constructor istrstream (char *str, int n) ; 

istrsteam(signed char *str, int); 
istrstream (unsigned char *str, int); 

Each of the three constructors above makes an istrstream using up to n bytes 
of str. See "The three char types" in Chapter 1 of the Programmer's Guide for 
a discussion of character types. 



ofstream class 



fstream.h 



Provides input operations on afilebuf. This class is derived iromfstreambase 
and ostream. 

Public constructors 

Constructor 'of stream (); 

Makes an ofstream that isn't attached to a file. 

Constructor ofstream(const char *name, int mode = ios::out, 

int prot = filebuf : :openprot) ; 

Makes an ofstream, opens a file, and connects to it. 

Constructor ofstream (int fd) ; 

Makes an ofstream and connects to an open-file descriptor specified by fd. 

Constructor ofstream(int fd, char *buf, int len); 

Makes an ofstream connected to an open-file descriptor specified by fd. The 
buffer specified by bufof len is used by the ofstream. 
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ofstream class 



Public member functions 



open 



rdbuf 



void open (const char *name, int mode = ios::out, 
int prot = filebuf : :openprot) ; 

Opens a file for an ofstream. 

filebuf* rdbuf (); 
Returns the filebuf used. 



ostream class 



iostream.h 



Provides formatted and unformatted output to a streambuf. The « operator 
is overloaded for all fundamental types. This fos-based class is a base for 
constream, iostream, ofstre'am, ostrstream, and ostreamjwithassign. 

Public constructor 

Constructor ostream (streambuf *); 

Associates a given streambuf 'with the stream. 

Public member functions 



flush 



opfx 



osfx 



put 



ostream& flush () ; 
Flushes the stream. 

int opfx() ; 

The opfx function is called by output functions prior to inserting to an 
output stream, opfx returns if the ostream has a nonzero error state. 
Otherwise, opfx returns a nonzero value. 

void osfx() ; 

The osfx function performs post output operations. If ios\:unitbuf 'is on, opfx 

flushes the ostream. On failure, opfx sets ios:: 

failbit. 

ostreamk put (unsigned char ch) ; 
ostream& put (char ch) ; 
ostreamk put (signed char ch) ; 

Inserts the character. 
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ostream class 



seekp ostream& seekp ( streampos ) ; 

Moves to an absolute position (as returned from tellp). 

seekp ostreamk seekp (streamoff, seek_dir) ; 

Moves to a position relative to the current position, following the 
definition: enum seek_dir {beg, cur, end}; 

tellp streampos tellp (); 

Returns the current stream position. 

write ostream& write(const signed char*, int n) ; 

ostreamk write (const unsigned char*, int n) ; 
ostream& write (const char*, int n) ; 

Inserts n characters (nulls included). 

ostream_withassign class iostream.h 

This class is an ostream with an added assignment operator. 

Public constructor 

Constructor ostream_withassign ( ) ; 

Default constructor (calls ostream's constructor). 

Public member functions 

None (although the = operator is overloaded). 

ostrstream class strstrea.h 

Provides output operations on a strstreambuf. This class is derived from 
strstreambase and ostream. 

Public'constructors 

Constructor ostrstreamO; 
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Makes a dynamic ostrstream. 

Constructor ostrstream (char *buf, int len, int mode = ios::out); 

ostrstream(signed char *buf, int len, int mode = ios::out); 
ostrstream (unsigned char *buf, int len, int mode = ios::out); 

Each of the three constructors above makes a ostrstream with a specified 
len-byte buffer. If the file-opening mode is iosr.app or iosr.ate, the get/put 
pointer is positioned at the null character of the string. See "The three char 
types" in Chapter 1 of the Programmer's Guide for a discussion of character 
types. 

Public member functions 



pcount 



str 



int pcount ( ) ; 

Returns the number of bytes currently stored in the buffer. 

char *str() ; . 

Returns and freezes the buffer. You must deallocate it if it was dynamic. 



streambuf class 



iostream.h 



This is a base class for all other buffering classes. It provides a buffer 
interface between your data and storage areas such as memory or physical 
devices. The buffers created by streambuf are referred to as get, put, and 
reserve areas. The contents are accessed and manipulated by pointers that 
point between characters. 

Buffering actions performed by streambuf are rather primitive. Normally, 
applications gain access to buffers and buffering functions through a 
pointer to streambuf that is set by ios. Class ios provides a pointer to 
streambuf that provides a transparent access to buffer services for high-level 
classes. The high-level classes provide I/O formatting. 

Public constructors 



Constructor 



Constructor 



streambuf () ; 

Creates an empty buffer object. 

streambuf (char *buf, int size); 
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streambuf class 



Constructs an empty buffer buf and sets up a reserve area for size number of 
bytes. 

Public member functions 



inavail 
out_waiting 
sbumpc 
seekoff 



seekpos 

setbuf 

sgetc 

sgetn 

snextc 

sputbackc 

sputc 

sputn 



int in_avail ( ) ; 

Returns the number of characters remaining in the input buffer. 

int out_waiting() ; 

Returns the number of characters remaining in the output buffer. 

int sbumpc ( ) ; 

Returns the current character from the input buffer, then advances. 

virtual streampos seekoff (streamoff, ios: :seek_dir, 

int = (ios:: in | ios: : out); 

Moves the get and /or put pointer (the third argument determines which 
one or both) relative to the current position. 

virtual streampos seekpos (streampos, int = (ios:: in I ios: : out)); 

Moves the get or put pointer to an absolute position. 

virtual streambuf* setbuf (char *, int); 

Connects to a given buffer. 

int sgetc () ; 

Peeks at the next character in the input buffer. 

int sgetnfchar*, int n) ; 

Gets the next n characters from the input buffer. 

int snextc ( ) ; 

Advances to and returns the next character from the input buffer. 

int sputbackc (char) ; 

Returns a character to input. 

int sputc (int) ; 

Puts one character into the output buffer. 

int sputnfconst char*, int n) ; 

Puts n characters into the output buffer. 
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stossc 



void stossc () ; 

Advances to the next character in the input buffer. 

Protected member functions 



allocate 

base 

blen 

eback 

ebuf 

egptr 

epptr 

gbump 

gptr 

pbase 

pbump 

pptr 



int allocate () ; 

Sets up a buffer area. 

char *base ( ) ; 

Returns the start of the buffer area. 

int blen() ; 

Returns the length of the buffer area. 

char *eback() ; 

Returns the base of the putback section of the get area. 

char *ebuf () ; 

Returns the end+1 of the buffer area. 

char *egptr() ; 

Returns the end+1 of the get area. 

char *epptr() ; 

Returns the end+1 of the put area. 

void gbump (int) ; 

Advances the get pointer. 

char *gptr ( ) ; 

Returns the next location in the get area. 

char *pbase() ; 

Returns the start of the put area. 

void pbump (int) ; 

Advances the put pointer. 

char *pptr() ; 

Returns the next location in the put area. 
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streambuf class 



setb 


void setb (char *, char *, int = 




Sets the buffer area. 


setg 


void setg (char *, char *, char *); 




Initializes the get pointers. 


setp 


void setp(char *, char *)? 




Initializes the put pointers. 


unbuffered 


void unbuffered (int) ; 




Sets the buffering state. 


unbuffered 


int unbuffered () ; 




Returns nonzero if not buffered. 



strstreambase class 



strstrea.h 



Specializes ios to string streams. This class is entirely protected except for 
the member function strstreambase: :rdbuf. This class is a base for strstream, 
istrstream, and ostrstream. 

Public constructors 



Constructor 



Constructor 



strstreambase () ; 

Makes an empty strstreambase. 

strstreambase (char *, int, char *start); 

Makes an strstreambase with a specified buffer and starting position. 



Public member functions 



rdbuf 



strstreambuf * rdbuf (); 

Returns a pointer to the strstreambuf associated with this object. 



strstreambuf class 



strstrea.h 



Specializes streambuf for in-memory formatting. 
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Public constructors 



Constructor 



Constructor 



Constructor 



Constructor 



strstreambuf () ; 

Makes a dynamic strstreambuf. Memory will be dynamically allocated as 
needed. 

strstreambuf (void * (*)(long), void (*) (void *)); 

Makes a dynamic buffer with specified allocation and free functions. 

strstreambuf (int n) ; 

Makes a dynamic strstreambuf, initially allocating a buffer of at least n bytes. 

strstreambuf (char*, int, char *strt = 0); 

strstreambuf (signed char *, int, signed char *strt = 0); 

strstreambuf (unsigned char *, int, unsigned char *strt = 0); 

Each of the three constructors above makes a static strstreambuf 'with a 
specified buffer. If strt is not null, it delimits the buffer. See "The three char 
types" in Chapter 1 of the Programmer's Guide for a discussion of character 
types. 

Public member functions 



doallocate 



freeze 



overflow 



seekoff 



setbuf 



str 



virtual int doallocate () ; 

Performs low-level buffer allocation. 

void freeze (int = 1) ; 

If the input parameter is nonzero, disallows storing any characters in the 
buffer. Unfreeze by passing a zero. 

virtual int overflow (int) ; 

Flushes a buffer to its destination. Every derived class should define the 
actions to be taken. 

virtual streampos seekoff (streamoff, ios: :seek_dir, int); 

Moves the pointer relative to the current position. 

virtual streambuf* setbuf (char*, int); 

Specifies the buffer to use. 

char *str() ; 

Returns a pointer to the buffer and freezes it. 
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strstreambuf class 



sync 



underflow 



virtual int sync ( ) ; 

Establishes consistency between internal data structures and the external 
stream representation. 

virtual int underflow () ; 

Makes input available. This is called when a character is requested and the 
strstreambuf is empty. Every derived class should define the actions to be 
taken. 



strstream class 



strstrea.h 



Provides for simultaneous input and output on a strstreambuf. This class is 
derived from strstreambase and iostream. 



Public constructors 



Constructor 



Constructor 



str 



strstreamO; 

Makes a dynamic strstream. 

strstream (char *buf, int sz, int mode); 
strstream(signed char *buf, int sz, int mode); 
strstream (unsigned char *buf, int sz, int mode); 

Each of the three constructors above makes a strstream with a specified sz- 
byte buffer. If mode is iosr.app or iosr.ate, the get/put pointer is positioned at 
the null character of the string. See "The three char types" in Chapter 1 of 
the Programmer's Guide for a discussion of character types. 

Public member function 

char *str() ; 

Returns and freezes the buffer. The user must deallocate it if it was 
dynamic. 
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Persistent stream classes and 
macros 



For a discussion on 

how to use the 

persistent streams 

library, see Chapter 7 

in the Programmed 

Guide. 



Borland support for persistent streams consists of a class hierarchy and 
macros to help you develop streamable objects. This chapter is a reference 
for these classes and macros. It alphabetically lists and describes all the 
public classes that support persistent objects. The class descriptions are 

followed by descriptions of the DELTA macro and the streaming 

macros. The streaming macros are provided to simplify the declaration and 
definition of streamable classes. 



The persistent streams class hierarchy 



The persistent streams class hierarchy is shown in the following figure: 



Figure 5.1 

Streamable class 

hierarchy 



pstream 



A A A 



ipstream 



fpbase 



opstream 



ifpstream 



ofpstream 
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fpbase class 



f pbase class 



objstm.h 



Provides the basic operations common to all object file stream I/O. 

Constructors 

Constructor fpbase ( ) ; 

fpbase(const char *name, int omode, int prot = filebuf : :openprot) ; 

fpbase (int f) ; 

fpbase(int f, char *b, int len); 

Creates a buffered fpbase object. You can set the size and location of the 
buffer with the len and b arguments. You can open a file and attach it to the 
stream by specifying the name, mode, and protection (prot) arguments, or 
by using the file descriptor,/. 

Public member functions 



attach 



close 



open 



rdbuf 



setbuf 



void attach (int f ) ; 

Attaches the file with descriptor/ to this stream if possible. Sets ios::state 
accordingly. 

void closet) ; 

Closes the stream and associated file. 

void open (const char *name, int mode, int prot = filebuf : :openprot) ; 

Opens the named file in the given mode (app, ate, in, out, binary, trunc, 
nocreate, noreplace) and protection. The opened file is attached to this 
stream. 

filebuf * rdbuf (); 

Returns a pointer to the current file buffer. 

void setbuf (char *buf, int len); 

Sets the location the buffer to buf and the buffer size to len. 



ifpstream class 



objstrm.h 



Provides the base class for reading (extracting) streamable objects from file 
streams. 
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Public constructors 



Constructor ifpstream(); 

ifpstream (const char *name, int mode = ios::in, 

int prot = filebuf : :openprot) ; 
ifpstream (int f ) ; 
ifpstream(int f, char *b, int len); 

Creates a buffered ifpstream object. You can set the size and location of the 
buffer with the len and b arguments. You can open a file and attach it to the 
stream by specifying the name, mode, and protection arguments, or via the 
file descriptor,/. 



Public member functions 



°P en void open(const char *name, int mode = ios::in, 

int prot = filebuf : :openprot) ; 

Opens the named file in the given mode (app, ate, in, out, binary, trunc, 
nocreate, or noreplace) and protection. The default mode is in (input) with 
openprot protection. The opened file is attached to this stream. 

rdbuf filebuf * rdbuf(); 

Returns a pointer to the current file buffer. 

ipstream class objstrm.h 

Provides the base class for reading (extracting) streamable objects. 

Public constructors 

Constructor ipstream (streambuf *buf); 

Creates a buffered ipstream with the given buffer. The state is set to 0. 

Public member functions 

find TStreamableBase * find(P_id_type Id); 

Returns a pointer to the object corresponding to Id. 

freadBytes V oid freadBytes( void *data, size_t sz ); 
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ipstream class 



freadString 



getVersion 
read Byte 
read Bytes 
readString 



readWord 



readWord16 



readWord32 



registerObject 



Reads into the supplied buffer (data) the number of bytes specified by sz. 

char * freadString () ; 

Reads a string from the stream. Determines the length of the string and 
allocates a character array of the appropriate length. Reads the string into 
this array and returns a pointer to the string. The caller is expected to free 
the allocated memory block. 

char *f readString ( char *buf, unsigned maxLen ); 

Reads a string from the stream into the supplied buffer (buf). If the length of 
the string is greater than maxLen-1, reads nothing. Otherwise reads the 
string into the buffer and appends a null terminating byte. 

uint32 getVersion () const; 

Returns the object version number. 

uint8 readByteO ; 

Returns the byte at the current stream position. 

void readBytes(void *data, size_t sz); 

Reads sz bytes from current stream position, and writes them to data. 

char * readString ( ) ; 

char * readString (char *buf, unsigned maxLen); 

readStringO allocates a buffer large enough to contain the string at the 
current stream position. Reads the string from the stream into the buffer. 
The caller must free the buffer. 

readString(char *buf, unsigned maxLen) reads the string at the current stream 
position into the buffer specified by buf. If the length of the string is greater 
than maxLen-1, reads nothing. Otherwise reads the string into the buffer 
and appends a null terminating byte. 

uint32 readWord () ; 

Returns the word at the current stream position. 

uintl6 readWordl6 ( ) ; 

Returns the 16-bit word at the current stream position. 

uint32 readWord32 ( ) ; 

Returns the 32-bit word at the current stream position. 

void registerObject (TStreamableBase * adr); 

Registers the object pointed to by adr. 
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seekg 



tellg 



ipstreamk seekg (streampos pos) ; 

ipstreamk seekg (streamoff off, ios: :seek_dir) ; 

The first form moves the stream position to the absolute position given by 
pos. The second form moves to a position relative to the current position by 
an offset off (+ or -) starting at ios::seek_dir. ios::seek_dir can be set to beg 
(start of stream), cur (current stream position), or end (end of stream). 

streampos tellg () ; 

Returns the (absolute) current stream position. 



Protected constructors 



Constructor ipstream(); 

The protected form of the constructor does not initialize the buffer pointer 
bp. Use init to set the buffer and state. 

Protected member functions 



read Data 



readPrefix 



readSuffix 



readVersion 



void * readData (const ObjectBuilder * ,TStreamableBase *& mem) ; 

Invokes the appropriate read function to read from the stream to the object 
pointed to by mem. If mem is 0, the appropriate build function is called first. 

See also: TStreamableClass, and the read and build member functions of each 
streamable class 

const ObjectBuilder * readPrefix () ; 

Returns the TStreamableClass object corresponding to the class name stored 
at the current position. 

void readSuffix () ; 

Reads and checks the object's suffix. 

See also: ipstream::readPrefix 

void readVersion ( ) ; 

Reads the version number of the input stream. 
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ipstream class 



Operator » 



Friends 



friend 


ipstream& operator 


» 


ipstreamk 


ps, 


signed char & ch) ; 


friend 


ipstreamk operator 


» 


ipstream& 


ps, 


unsigned char & ch) ; 


friend 


ipstreamk operator 


» 


ipstreamk 


ps, 


signed short & sh) ; 


friend 


ipstream& operator 


» 


ipstreamk 


ps, 


unsigned short & sh) ; 


friend 


ipstreamk operator 


» 


ipstream& 


ps, 


signed int & i) ; 


friend 


ipstream& operator 


» 


ipstreamk 


ps, 


unsigned int & i) ; 


friend 


ipstreamk operator 


» 


ipstream& 


ps, 


signed long & 1) ; 


friend 


ipstreamk operator 


» 


ipstream& 


ps, 


unsigned long & 1) ; 


friend 


ipstreamk operator 


» 


ipstreamk 


ps, 


float & f); 


friend 


ipstreamk operator 


» 


ipstream& 


ps, 


double & d) ; 


friend 


ipstreamk operator 


» 


ipstreamk 


ps, 


long double & d) ; 


friend 


ipstreamk operator 


» 


ipstream& 


ps, 


TStreamableBase t) ; 


friend 


ipstream& operator 


» 


ipstreamk 


ps, 


void *t); 



Extracts (reads) from the ipstream ps, to the given argument. A reference to 
the stream is returned, letting you chain » operations in the usual way. 
The data type of the argument determines how the read is performed. For 
example, reading a signed char is implemented using readByte. 



ofpstream class 



objstrm.h 



Provides the base class for writing (inserting) streamable objects to file 
streams. 

Public constructors 

Constructor ofpstreamO; 

ofpstream(const char *name, int mode = ios::out, 

int prot = filebuf : :openprot) ; 
ofpstream (int f) ; 
ofpstream(int f, char *b, int len) ; 

Creates a buffered ofpstream object. You can set the size and address of the 
buffer with the len and b arguments. A file can be opened and attached to 
the stream by specifying the name, mode, and protection arguments, or by 
using the file descriptor,/. 
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Public member functions 



open 



rdbuf 



void open(char *name, int mode = ios::out, int prot = filebuf : :openprot) ; 

Opens the named file in the given mode (app, ate, in, out, binary, trunc, 
nocreate, or noreplace) and protection. The default mode is out (output) with 
openprot protection. The opened file is attached to this stream. 

filebuf * rdbuf (); 

Returns the current file buffer. 



opstream class 



objstrm.h 



Provides the base class for writing (inserting) streamable objects. 



Constructor 



Destructor 



Public constructors and destructor 



opstream (streambuf *buf ) ; 

This constructor creates a buffered opstream with the given buffer. The state 
is set to 0. 



-opstream () ; 

Destroys the opstream object. 

See also: pstream::init 



Public member functions 



findObject 
findVB 
flush 
fwriteBytes 



P_id_type findObject (TStreamableBase *adr) ; 
Returns the type ID for the object pointed to by adr. 
P_id_type findVB (TStreamableBase *adr) ; 
Returns a pointer to the virtual base. 

opstreamk flush () ; 
Flushes the stream. 

void fwriteBytes ( const void *data, size_t sz ) ; 

Writes the specified number of bytes (sz) from the supplied buffer {data) to 
the stream. 
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fwriteString void fwriteStringf const char *str ); 

Writes the specified character string (str) to the stream. 
registerObject void registerObject(TStreamableBase *adr) ; 

Registers the class of the object pointed to by adr. 
regiSterVB void registerVB(TStreamableBase *adr); 

Registers a virtual base class. 

seekp opstreamk seekp(streampos pos); 

opstream& seekp (streamoff off ,ios: :seek_dir) ; 

The first form moves the stream's current position to the absolute position 
given by pos. The second form moves to a position relative to the current 
position by an offset off(+ or -) starting at ios::seek_dir . ios::seek_dir can be set 
to beg (start of stream), cur (current stream position), or end (end of stream). 

tellp streampos tellpO; 

Returns the (absolute) current stream position. 
writeByte void writeByte(uint8 ch) ; 

Writes the byte ch to the stream. 
wnteBytes vo id writeBytes (const void *data, size_t sz); 

Writes sz bytes from data buffer to the stream. 

writeObject V oid writeObject( const TStreamableBase *t, int isPrt = 0, 

Moduleld mid = GetModuleldO ); 

Writes the object that is pointed to by t to the output stream. The isPtr 
indicates whether the object was allocated from the heap. 

wnteStnng void writeString (const char *str) ; 

Writes str to the stream. 
WNteWord void writeWord(uint32 us); 

Writes the 32-bit word us to the stream. 
WliteWord16 void writeWordl6(uintl6 us); 

Writes the 16-bit word us to the stream. 
writeWord32 void writeWord32(uint32 us) ; 

Writes the 32-bit word us to the stream. 
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Protected constructors 



Constructor 



writeData 



writePrefix 



writeSuffix 



opstream () ; 

This protected form of the constructor does not initialize the buffer pointer 
bp. Use init to set the buffer and state. 

Protected member functions 

void writeData (TStreamableBase *t); 

Writes data to the stream by calling the appropriate class's write member 
function for the object being written. 

See also: TStreamableBase and the write functions in the streamable classes 

void writePrefix (const TStreamableBase *t); 

Writes the class name prefix to the stream. The « operator uses this 
function to write a prefix and suffix around the data written with writeData. 
The prefix /suffix is used to ensure type-safe stream I/O. 

See also: ipstream:readPrefix 

void writeSuffix (const TStreamableBase *t) ; 

Writes the class name suffix to the stream. The « operator uses this 
function to write a prefix and suffix around the data written with writeData. 
The prefix/suffix is used to ensure type-safe stream I/O. 

See also: ipstream:readPrefix 



Friends 



Operator « 



friend opstreamk operator 


« 


!opstream& 


ps, 


signed char ch) ; 


friend opstream& operator 


« 


(opstreamk 


ps, 


unsigned char ch) ; 


friend opstream& operator 


« 


opstream& 


ps, 


signed short sh) ; 


friend opstream& operator 


« 


opstream& 


ps, 


unsigned short sh) ; 


friend opstreamk operator 


« 


(opstream& 


ps, 


signed int i) ; 


friend opstreamk operator 


« 


(opstreamk 


ps, 


unsigned int i) ; 


friend opstream& operator 


« 


(opstreamk 


ps, 


signed long 1) ; 


friend opstream& operator 


« 


(opstream& 


ps, 


unsigned long 1) ; 


friend opstreamk operator 


« 


(opstreamk 


ps, 


float re- 


friend opstream& operator 


« 


(opstreamk 


ps, 


double d) ; 


friend opstreamk operator 


« 


opstreamk 


ps, 


long double d) ; 


friend opstreamk operator 


« 


opstreamk 


ps, 


TStreamableBase& t); 
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pstream class 



Inserts (writes) the given argument to the given ipstream object. The data 
type of the argument determines the form of write operation employed. 

objstrm.h 

pstream is the base class for handling streamable objects. 

Type definitions 



PointerTypes e num PointerTypes{ptNull, ptlndexed, ptObject} 

Enumerates object pointer types. 

Public constructors and destructor 



Constructor 



Destructor 



pstream (streambuf *buf); 

This constructor creates a buffered pstream with the given buffer. The state 
is set to 0. 

virtual -pstream () ; 

Destroys the pstream object. 

Public member functions 



bad 



clear 



eof 



fail 



good 



int bad() const; 

Returns nonzero if an error occurred. 

void clear (int aState = 0); 

Set the stream state to the given value (defaults to 0). 

int eof() const; 

Returns nonzero after end of stream. 

int fail() const; 

Returns nonzero if a stream operation failed. 

int good() const; 
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pstream class 



rdbuf 



rdstate 



Returns nonzero if no state bits are set (that is, if no errors occurred). 

streambuf * rdbuf () const; 

Returns a pointer to this stream's assigned buffer. 

See also: pstream::pb 

int rdstate () const; 

Returns the current state value. 



Operator void *() 



Operator ! () 



Operators 



operator void *() const; 
Converts to a void pointer. 
See also: pstream: :f ail 

int operator ! () const; 

The NOT operator. Returns if the operation has failed (that is, if 
pstream::fail returned nonzero); otherwise, returns nonzero. 

See also: pstream::fail 



Protected data members 



bp 



state 



streambuf *bp; 

Pointer to the stream buffer. 

int state; 

Format state flags. Use rdstate to access the current state. 

See also: pstream: -.rdstate 



Constructor 



Protected constructors 



pstream () ; 

This form of the constructor does not initialize the buffer pointer bp. Use 
init and setstate to set the buffer and state. 
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Protected member functions 



init 



setstate 



void init (streambuf *sbp) ; 

Initializes the stream: sets state to and bp to sbp. 

void setstate (int b) ; 

Updates the state data member with state 1= (b & OxFF) 



TStreamableBase class 



objstrm.h 



class TStreamableBase 

Classes that inherit from TStreamableBase are known as streamable classes, 
meaning their objects can be written to and read from streams. If you want 
to develop your own streamable classes, you should make sure that 
TStreamableBase is somewhere in their ancestry. Using an existing 
streamable class as a base, of course, is an obvious way of achieving this. 
Use multiple inheritance to derive a class from TStreamableBase if your class 
must also fit into an existing class hierarchy. 



Typejd 



Type definitions 



typedef const char *Type_id; 
Describes type identifiers. 



Public destructor 



Destructor 



virtual -TStreamableBase ( ) {}; 
Destroys the TStreamableBase object. 



CastablelD 



Public member functions 



virtual Type_id CastablelD () const = 0; 

Available only when the library is build without RTTI. 

Provides support for typesafe downcasting. Returns a string containing the 
type name. 
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FindBase virtual void *FindBase( Type_id id ) const; 

Available only when the library is build without RTTI. 

Returns a pointer to the base class. 
MostDerived virtual void *MostDerived() const = 0; 

Available only when the library is build without RTTI. 

Returns a void pointer to the actual streamed object. 

TStreamableClass class streambl.h 

Used by the private database class and pstream in streamable class 
registration. 

Public constructor 

Constructor TStreamableClass (const char *n, BUILDER b, int d=NoDelta, 

Moduleld mid = GetModuleldO ) ; 

Creates a TStreamableClass object with the given name (n) and the given 
builder function (b), then registers the type. Each streamable class, for 
example TClassname, has a build member function of type BUILDER. For 
type-safe object-stream I/O, the stream manager needs to access the names 
and the type information for each class. To ensure that the appropriate 
functions are linked into any application using the stream manager, you 
must provide a reference such as: 

TStreamableClass RegClassName; 

where TClassName is the name of the class for which objects need to be 
streamed. (Note that RegClassName is a single identifier.) This not only 
registers TClassName (telling the stream manager which build function to 
use), it also automatically registers any dependent classes. You can register 
a class more than once without any harm or overhead. 

Invoke this function to provide raw memory of the correct size into which 
an object of the specified class can be read. Because the build procedure 
invokes a special constructor for the class, all virtual table pointers are 
initialized correctly. 
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The DEL TA macro 

is provided only for 

backward 

compatibility and 

should not be used in 

new code. 



The distance, in bytes, between the base of the streamable object and the 
beginning of the TStreamableBase component of the object is d. Calculate d 
by using the DELTA macro. For example, 

TStreamableClass RegTClassName = TStreamableClass ( "TClassName" , 
TClassName: -.build, _ _DELTA (TClassName) ) ; 

See also: TStreamableBase, ipstream, opstream 



Friends 



The classes opstream and ipstream are friends of TStreamableClass. 



TStreamer class 



objstrm.h 



class TStreamer 

Base class for all streamable objects. 

Public member functions 



GetObject 



Constructor 



TStreamableBase *GetObject() const 

Returns the address of the TStreamableBase component of the streamable 
object. 

Protected constructors 

TStreamer ( TStreamableBase *obj ) 

Constructs the TStreamer object, and initializes the streamable object 
pointer. 

Protected member functions 



Read 



StreamableName 



virtual void *Read( ipstreamk, uint32 ) const = 0; 

This pure virtual member function must be redefined for every streamable 
class. It must read the necessary data members for the streamable class 
from the supplied ipstream. 

virtual const char *StreamableName() const = 0; 
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This pure virtual member function must be redefined for every streamable 
class. StreamableName returns the name of the streamable class, which is 
used by the stream manager to register the streamable class. The name 
returned must be a O-terminated string. 

Write virtual void Write ( opstream& ) const = 0; 

This pure virtual function must be redefined for every streamable class. It 
must write the necessary streamable class data members to the supplied 
opstream object. Write is usually implemented by calling the base class's 
Write (if any), and then inserting any additional data members for the 
derived class. 



DELTA macro streambl.h 

#define _ _DELTA( d ) (FP_0FF( (TStreamable *) (d *)1)-1) 
Provided only for 

backward Calculates the distance, in bytes, between the base of the streamable object 

compatibility and an( ^ ^g beginning of the TStreamableBase component of the object. 

should not be used in ° ° r ' 

new code. 

DECLARE_STREAMABLE macro objstrm.h 

DECLARE_STREAMABLE(exp, els, ver) 

The DECLARE_STREAMABLE macro is used within a class definition to 
add the members that are needed for streaming. Because it contains access 
specifiers, it should be followed by an access specifier or be used at the end 
of the class definition. The first parameter should be a macro, which in turn 

should conditionally expand to either import or export, depending on 

whether or not the class is to be imported or exported from a DLL. The 
second parameter is the streamable class name. The third parameter is the 
object version number. 

See also: Chapter 8 in the Programmer's Guide 

DECLARE_STREAMABLE_FROM_BASE macro objstrm.h 

DECLARE_STREAMABLE_FROM_BASE(exp, els, ver) 

DECLARE_STREAMABLE_FROM_BASE is used in the same way as 
DECLARE_STREAMABLE; it should be used when the class being defined 
can be written and read using Read and Write functions defined in its base 
class without change. This usually occurs when a derived class overrides 
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virtual functions in its base or provides different constructors, but does not 
add any data members. (If you used DECLARE_STREAMABLE in this 
situation, you would have to write Read and Write functions that merely 
called the base's Read and Write functions. Using 
DECLARE_STREAMABLE_FROM_BASE prevents this.) 

DECLARE_ABSTRACT_STREAMABLE macro objstrm.h 

DECLARE_ABSTRACT_STREAMABLE(exp, els, ver) 

This macro is used in an abstract class. DECLARE_STREAMABLE doesn't 
work with an abstract class because an abstract class can never be 
instantiated, and the code that attempts to instantiate the object (Build) 
causes compiler errors. 

DECLARE_STREAMER macro objstrm.h 

DECLARE_STREAMER(exp, els, ver ) 

This macro defines a nested class within your streamable class; it contains 
the core of the streaming code. DECLARE_STREAMER declares the Read 
and Write function declarations, whose definitions you must provide, and 
the Build function that calls the TStreamableClass constructor. See 
DECLARE_STREAMABLE for an explanation of the parameters. 

DECLARE_STREAMER_FROM_BASE macro objstrm.h 

DECLARE_STREAMER_FROM_BASE ( exp, els, base ) 

This macro is used by DECLARE_STREAMABLE_FROM_BASE. It declares 
a nested Streamer class without the Read and Write functions. See 
DECLARE_STREAMABLE for a description of the parameters. 

DECLARE_ABSTRACT_STREAMER macro objstrm.h 

define DECLARE_ABSTRACT_STREAMER ( exp, els, ver ) 

This macro is used by DECLARE_ABSTRACT_STREAMABLE. It declares a 
nested Streamer class without the Build function. See 
DECLARE_STREAMABLE for an explanation of the parameters. 
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DECLARE_CASTABLE macro objstrm.h 

DECLARE_CASTABLE 

This macro provides declarations that provide a rudimentary typesafe 
downcast mechanism. This is useful for compilers that don't support run- 
time type information. 

DECLARE_STREAMABLE_OPS macro objstrm.h 

DECLARE_STREAMABLE_OPS ( C 1 S ) 

Declares the inserters and extractors. For template classes, 
DECLARE_STREAMABLE_OPS must use class<. . .> as the macro 
argument; other DECLARES take only the class name. 

DECLARE_STREAMABLE_CTOR macro objstrm.h 

DECLARE_STREAMABLE_CTOR ( els ) 

Declares the constructor called by the Streamer r.Build function. 

1MPLEMENT_STREAMABLE macros objstrm.h 

IMPLEMENT_STREAMABLE (els) 
IMPLEMENT_STREAMABLEl(cls, basel) 

IMPLEMENT_STREAMABLE2(cls, basel, base2) 

IMPLEMENT_STREAMABLE3(cls, basel, base2, base3) 

IMPLEMENT_STREAMABLE4(cls, basel, base2, base3, base4) 

IMPLEMENT_STREAMABLE5(cls, basel, base2, base3, base4, base5) 

The IMPLEMENT_STREAMABLE macros generate the registration object 
for the class via IMPLEMENT_STREAMABLE_CLASS, and generate the 
various member functions that are needed for a streamable class via 
IMPLEMENT_ABSTRACT_STREAMABLE. 

IMPLEMENT_STREAMABLE is used when the class has no base classes 
other than TStreamableBase. Its only parameter is the name of the class. 
The numbered versions (IMPLEMENT_STREAMABLE1, 
IMPLEMENT_STREAMABLE2, and so on) are for classes that have bases. 
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Each base class, including all virtual bases, must be listed in the 
IMPLEMENT_STREAMABLE macro invocation. 

The individual components comprising these macros can be used 
separately for special situations, such for as custom constructors. 

IMPLEMENT_STREAMABLE_CLASS macro objstrm.h 

IMPLEMENT_STREAMABLE_CLASS (els) 
Constructs a TStreamableClass class instance. 

IMPLEMENT_STREAMABLE_CTOR macros objstrm.h 

IMPLEMENT_STREAMABLE_CTOR (els) 

IMPLEMENT_STREAMABLE_CTORl(cls, basel) 

IMPLEMENT_STREAMABLE_CT0R2(cls, basel, base2) 

IMPLEMENT_STREAMABLE_CT0R3(cls, basel, base2, base3) 

IMPLEMENT_STREAMABLE_CT0R4(cls, basel, base2, base3, base4) 

IMPLEMENT_STREAMABLE_CT0R5(cls, basel, base2, base3, base4, base5) 

Defines the constructor called by the Build function. All base classes must 
be listed in the appropriate macro. 

IMPLEMENT_STREAMABLE_POINTER macro objstrm.h 

IMPLEMENT_STREAMABLE_POINTER ( c 1 S ) 

Creates the instance pointer extraction operator (»). 

IMPLEMENT_CASTABLE_ID macro objstrm.h 

IMPLEMENT_CASTABLE_ID ( els ) 

Sets the typesafe downcast identifier. 

IMPLEMENT_CASTABLE macros objstrm.h 

IMPLEMENT CASTABLEf els ) 
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IMPLEMENT_CASTABLE1 ( els 

IMPLEMENT_CASTABLE2 ( els 

IMPLEMENT_CASTABLE3 ( els 

IMPLEMENT_CASTABLE4 ( els 

IMPLEMENTS ASTABLE 5 ( els 

These macros implement code that supports the typesafe downcast 
mechanism. 

IMPLEMENT_STREAMER macro objstrm.h 

IMPLEMENT_STREAMER ( els ) 

Defines the Streamer constructor. 

IMPLEMENT J\BSTRACT_STREAMABLE macros objstrm.h 

IMPLEMENT_ABSTRACT_STREAMABLE ( els ) 
IMPLEMENT_ABSTRACT_STREAMABLE1 ( els 
IMPLEMENT_ABSTRACT_STREAMABLE2 ( els 
IMPLEMENT_ABSTRACT_STREAMABLE3 ( els 
IMPLEMENT_ABSTRACT_STREAMABLE4 ( els 
IMPLEMENT_ABSTRACT_STREAMABLE5 ( els 

This macro expands to IMPLEMENT_STREAMER (which defines the 
Streamer constructor), IMPLEMENT_STREAMABLE_CTOR (which defines 
the TStreamableClass constructor), and 

IMPLEMENT_STREAMABLE_POINTER (which defines the instance 
pointer extraction operator). 

IMPLEMENT_STREAMABLE_FROM_BASE macro objstrm.h 

IMPLEMENT_STREAMABLE_FROM_BASE ( els, basel ) 

This macro expands to IMPLEMENT_STREAMABLE_CLASS (which 
constructs a TStreamableClass instance), 

IMPLEMENT_STREAMABLE_CTORl (which defines a one base class 
constructor that is called by Build), and 

IMPLEMENT_STREAMABLE_POINTER (which defines the instance 
pointer extraction operator). 
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The C++ container classes 



See Chapter 7 in the 

Programmer^ Guide 

for information on 

using containers. 



This chapter is a reference guide to the Borland C++ container classes. Each 
container class belongs to one of the following groups, which are listed here 
with their associated header-file names. 



i Array (arrays.h) 

i Association (assoc.h) 

i Bag (bags.h) 

i Binary tree (binimp.h) 

i Dequeue (deques.h) 

i Dictionary (dict.h) 

i Double-linked list (dlistimp.h) 



■ Hash table (hashimp.h) 

■ List (listimp.h) 

■ Queue (queues.h) 

■ Set (sets.h) 

■ Stack (stacks .h) 

■ Vector (vectimp.h) 



TMArrayAsVector template 



arrays.h 



template <class T, class Alloo class TMArrayAsVector; 

TMArrayAsVector implements a managed array of objects of type T, using a 
vector as the underlying implementation. It requires an operator == for 
type T. The memory manager Alloc provides class-specific new and delete 
operators. 



CondFunc 



IterFunc 



Type definitions 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to the ForEach member function. 
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Constructor 



Public constructors 



TMArrayAsVector ( int upper, int lower 



int delta = 



Creates an array with an upper bound of upper, a lower bound of lower, and 
a growth delta of delta. 

Public member functions 



Add 



AddAt 



ArraySize 



BoundBase 



Destroy 



Detach 



Find 



int Add( const T& t ) 

Adds a T object at the next available index at the end of an array. Adding 
an element beyond the upper bound leads to an overflow condition. If 
overflow occurs and delta is nonzero, the array is expanded (by sufficient 
multiples of delta bytes) to accommodate the addition. If delta is zero, Add 
fails. Add returns if it couldn't add the object. 

int AddAt ( const T& t, int loc ) 

Adds a T object at the specified index. If that index is occupied, it moves the 
object up to make room for the added object. If loc is beyond the upper 
bound, the array is expanded if delta (see the constructor) is nonzero. If delta 
is zero, attempting to AddAt beyond the upper bound gives an error. 

unsigned ArraySize () const; 

Returns the current number of cells allocated. 

int BoundBase ( unsigned loc ) const; 

Boundbase adjust vectors, which are zero-based, to arrays, which aren't 
zero-based. See ZeroBase. 

int Destroy ( int i ) 

Removes the object at the given index. The object will be destroyed. 

int Destroy ( const T& t ) 

Removes the given object and destroys it. 

int Detach ( int loc ) 

int Detach ( const T& t) 

The first version removes the object at loc; the second version removes the 
first object that compares equal to the specified object. 
See also: TShouldDelete::ownsElements 

int Find( const T& t ) const; 
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FirstThat 



Flush 

ForEach 

GetltemslnContainer 

Grow 

HasMember 

InsertEntry 

IsEmpty 

IsFull 



LastThat 



Finds the specified object and returns the object's index; otherwise returns 
INT_MAX. 

T *FirstThat(CondFunc cond, void *args ) const; 

Returns a pointer to the first object in the array that satisfies a given 
condition. You supply a test-function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 

See also: LastThat 

void Flush ( ) ; 

Removes all elements from the array without destroying the array. 

See also: Detach 

void ForEach (IterFunc iter, void *args ) 

ForEach executes the given function iter for each element in the array. The 
args argument lets you pass arbitrary data to this function. 

unsigned GetltemslnContainer () const; 

Returns the number of items in the array, as distinguished from ArraySize, 
which returns the size of the array. 

void Grow( int loc ) 

Increases the size of the array, in either direction, so that loc is a valid index. 

int HasMember ( const T& t ) const; 

Returns 1 if the given object is found in the array; otherwise returns 0. 

void InsertEntry( int loc ) 

Creates an object and inserts it at loc, moving entries above loc up by one. 

int IsEmpty () const; 

Returns 1 if the array contains no elements; otherwise returns 0. 

int IsFull () const; 

Returns 1 if the array is full; otherwise returns 0. The array is full if delta is 
not equal to and if the number of items in the container equals the value 
returned by ArraySize. 

T *LastThat( CondFunc cond, void *args ) const; 

Returns a pointer to the last object in the array that satisfies a given 
condition. You supply a test function pointer cond that returns true for a 
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certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 

See also: FirstThat, ForEach 

LowerBound i n t LowerBound ( ) const; 

Returns the array's lowerbound. 

Reallocate j n t Reallocate ( unsigned sz, unsigned offset = ) 

If delta (see the constructor) is zero, reallocate returns 0. Otherwise, reallocate 
tries to create a new array of size sz (adjusted upwards to the nearest 
multiple of delta). The existing array is copied to the expanded array and 
then deleted. In an array of pointers, the entries are zeroed for each unused 
element. In an array of objects, the default constructor is invoked for each 
unused element, offset is the location in the new vector where the first 
element of the old vector should be copied. This is needed when the array 
has to be extended downward. 

RemoveEntry V oid RemoveEntry( int loc ) 

Removes element at the loc index into the array, and reduces the array by 
one element. Elements from index (loc + 1) upward are copied to positions 
loc, (loc + 1), and so on. The original element at loc is lost. 

SetData void SetData( int loc, const T& t ) 

The given t replaces the existing element at the index loc. 

UpperBound i n t UpperBoundO const; 

Returns the array's current upperbound. 

ZeroBase unsigned ZeroBase( int loc ) const; 

Returns the location relative to lowerbound (loc - lowerbound). 

Protected member functions 



ItemAt 



T ItemAt ( int i ) const; 

Returns a copy of the object stored at location i. 

Operators 



operator [ ] 



T& operator [] ( int loc ) 

T& operator [] ( int loc ) const; 
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Returns a reference to the element at the location specified by loc. the 
non-const version resizes the array if it's necessary to make loc a valid 
index. The const version throws an exception in the debugging version on 
an attempt to index out of bounds. 



TMArrayAsVectorlterator template 



arrays.h 



template <class T, class Alloo class TMArrayAsVectorlterator; 
Implements an iterator object to traverse TMArrayAsVector objects. 

Public constructors 

Constructor TMArrayAsVectorlterator! const TMArrayAsVector<T, Alloo & a ) : 

Creates an iterator object to traverse TMArrayAsVector objects. 

Public member functions 



Current 



Restart 



const T& Current ( ) ; 

Returns the current object. 

void Restart!) ; 

void Restart! unsigned start, unsigned stop ); 

Restarts iteration from the beginning, or over the specified range. 



operator ++ 



operator int 



Operators 



const T& operator ++(int); 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

const T& operator ++(); 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 

operator int(). const; 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 
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TArrayAsVector template arrays.h 

template <class T> class TArrayAsVector; 

TArrayAsVector implements an array of objects of type T, using a vector as 
the underlying implementation. T Standard Allocator is used to manage 
memory. See TMArrayAsVector on page 297 for members. 

Public constructors 

Constructor TArrayAsVector ( int upper, int lower =0, int delta = ) : 

Creates an array with an upper bound of upper, a lower bound of lower, and 
a growth delta of delta. 

TArrayAsVectorlterator template arrays.h 

template <class T> class TArrayAsVectorlterator; 

Implements an iterator object to traverse TArrayAsVector objects. See 
TMArrayAsVectorlterator on page 301 for members. 

Public constructors 

Constructor TArrayAsVectorlterator ( const TArrayAsVector<T> & a ) 

Creates an iterator object to traverse TArrayAsVector objects. 

TMIArrayAsVector template arrays.h 

template <class T, class Alloo class TMIArrayAsVector; 

Implements a managed, indirect array of objects of type T, using a vector as 
the underlying implementation. 

Type definitions 

CondFunc typedef int ( *CondFunc) (const T '&, void Mr- 

Function type used as a parameter to FirstThat and LastThat member 
functions. 
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IterFunc 



typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public constructors 



Constructor 



TMIArrayAsVector ( int upper, int lower 



int delta 



Add 



AddAt 



ArraySize 
Destroy 



Detach 



Creates an indirect array with an upper bound of upper, a lower bound of 
lower, and a growth delta of delta. 

Public member functions 

int Add( T *t ); 

Adds a pointer to a T object at the next available index at the end of an 
array. Adding an element beyond the upper bound leads to an overflow 
condition. If overflow occurs and delta is nonzero, the array is expanded (by 
sufficient multiples of delta bytes) to accommodate the addition. If delta is 
zero, Add fails. Add returns if the object couldn't be added. 

int AddAt ( T *t, int loc ); 

Adds a pointer to a T object at the specified index. If that index is occupied, 
it moves the object up to make room for the added object. If loc is beyond 
the upper bound, the array is expanded if delta (see the constructor) is 
nonzero. If delta is zero, attempting to AddAt beyond the upper bound 
returns 0. Otherwise it returns 1. 

unsigned ArraySize () const; 

Returns the current number of cells allocated. 

int Destroy ( int i ) ; 

Removes the object at the given index. The object will be deleted. 

int Destroy ( T *t ) ; 

Removes the object pointed to by t and deletes it. 

int Detach ( int loc, DeleteType dt = NoDelete ); 
int Detach ( T *t, DeleteType dt = NoDelete ); 

The first version removes the object pointer at loc; the second version 
removes the specified pointer. The value of dt and the current ownership 
setting determine whether the object itself will be deleted. DeleteType is 
defined in the base class TShouldDelete as enum { NoDelete, Def Delete, 
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Find 



FirstThat 



Flush 



Delete } . The default value of dt, NoDelete, means that the object will not be 
deleted regardless of ownership. With dt set to Delete, the object will be 
deleted regardless of ownership. If dt is set to DefDelete, the object will be 
deleted only if the array owns its elements. 

See also: TShouldDeleter.oivnsElements 

int Find( const T *t ) const; 

Finds the first specified object pointer and returns the index. Returns 
INTJMAX not found. 

T *FirstThat( CondFunc cond, void *args ) const; 

Returns a pointer to the first element in the array that satisfies a given 
condition. You supply a test-function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the container meets the condition. 

See also: LastThat 

void Flush ( DeleteType dt = DefDelete ) 

Removes all elements from the array without destroying the array. The 
value of dt determines whether the elements themselves are destroyed. By 
default, the ownership status of the array determines their fate, as 
explained in the Detach member function. You can also set dt to Delete and 
NoDelete. 

See also: Detach 

void ForEach(IterFunc iter, void *args ) 

ForEach executes the given function iter for each element in the container. 
The args argument lets you pass arbitrary data to this function. 

GetltemslnContainer unsigned GetltemsInContainerO const; 

Returns the number of items in the array. 

int HasMemberf const T& t ) const; 

Returns 1 if the given object is found in the array; otherwise returns 0. 

int IsEmptyO const; 

Returns 1 if the array contains no elements; otherwise returns 0. 

int IsFull() const; 

Returns 1 if the array is full; otherwise returns 0. 

T *LastThat( CondFunc cond, void *args ) const; 



ForEach 



HasMember 



IsEmpty 



IsFull 



LastThat 
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LowerBound 



UpperBound 



Returns a pointer to the last element in the array that satisfies a given 
condition. You supply a test function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the container meets the condition. 

See also: FirstThat, ForEach 

int LowerBound () const; 

Returns the array's lowerbound. 

int UpperBound () const; 

Returns the array's current upperbound. 



Protected member functions 



BoundBase 



Grow 



InsertEntry 



ItemAt 



Reallocate 



RemoveEntry 



int BoundBase ( unsigned loc ) const; 

Boundbase adjusts vectors, which are zero-based, to arrays, which aren't 
zero-based. See ZeroBase. 

void Grow( int loc ) 

Increases the size of the array, in either direction, so that loc is a valid index. 

void InsertEntry ( int loc ) 

Creates an object and inserts it at loc. 

T ItemAt ( int i ) const; 

Returns a copy of the object stored at location i. 

int Reallocate! unsigned sz, unsigned offset = ) 

If delta (see the constructor) is zero, reallocate returns 0. Otherwise, reallocate 
tries to create a new array of size sz (adjusted upward to the nearest 
multiple of delta). The existing array is copied to the expanded array and 
then deleted. In an array of pointers the entries are zeroed. In an array of 
objects the default constructor is invoked for each unused element, offset is 
the location in the new vector where the first element of the old vector 
should be copied. This is needed when the array has to be extended 
downward. 

void RemoveEntry ( int loc ) 

Removes element at loc, and reduces the array by one element. Elements 
from index (loc + 1) upward are copied to positions loc, (loc + 1), and so on. 
The original element at loc is lost. 
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SetData 
SqueezeEntry 

ZeroBase 



operator [ ] 



void SetData ( int loc, const T& t ) 

The given t replaces the existing element at the index loc. 

void SqueezeEntry ( unsigned loc ) 

Removes element at loc, and reduces the array by one element. Elements 
from index (loc + 1) upward are copied to positions loc, (loc + 1), and so on. 
The original element at loc is lost. 

unsigned ZeroBase ( int loc ) const; 

Returns the location relative to lowerbound (loc - lowerbound). 

Operators 

T * & operator [] ( int loc ) 

T * & operator [] ( int loc ) const; 

Returns a reference to the element at the location specified by loc. the 
non-const version resizes the array if it's necessary to make loc a valid 
index. The const throws an exception in the debugging version on an 
attempt to index out of bounds. 



TMIArrayAsVectorlterator template 



arrays.h 



template <class T, class Alloo class TMIArrayAsVectorlterator; 

Implements an iterator object to traverse TMIArrayAsVector objects. Based 
on TMVectorlteratorlmp. 



Public constructors 



Constructor 



TMIArrayAsVectorlterator ( const TMIArrayAsVector<T, Alloo &a 
Creates an iterator object to traverse TMArrayAsVector objects. 



Public member functions 



Current 



Restart 



T * Cur rent (); 

Returns a pointer to the current object. 

void Restart () ; 
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void Restart ( unsigned start, unsigned stop ); 

Restarts iteration from the beginning, or over the specified range. 

Operators 

operator ++ con st T& operator ++(int); 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

const T& operator ++(); 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 

TIArrayAsVector template arrays.h 

template <class T> class TIArrayAsVector; 

Implements an indirect array of objects of type T, using a vector as the 
underlying implementation. T Standard Allocator is used to manage memory. 
See TMIArrayAsVector on page 302 for members. 

Public constructors 

Constructor TIArrayAsVector ( int upper, int lower =0, int delta = ) 

Creates an array with an upper bound of upper, a lower bound of lower, and 
a growth delta of delta. 

TIArrayAsVectorlterator template arrays.h 

template <class T> class TIArrayAsVectorlterator; 

Implements an iterator object to traverse TIArrayAsVector objects. Uses 
T Standard Allocator for memory management. See TMIArrayAsVectorlterator 
on page 306 for member functions and operators. 
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Public constructors 



Constructor TIArrayAsVectorIterator( const TIArrayAsVector<T> &a ) : 

TMIArrayAsVectorIterator<T,TStandardAllocator>(a) 

Creates an iterator object to traverse TI Array AsVector objects. 

TMSArrayAsVector template arrays.h 

template <class T, class Alloo class TMSArrayAsVector; 

Implements a sorted array of objects of type T, using a vector as the 
underlying implementation. With the exception of the AddAt member 
function, TMSArrayAsVector inherits its member functions and operators 
from TMArr ay AsVector. See TMArr ay AsVector on page 297 for members. 

Public constructors 

Constructor TMSArrayAsVector ( int upper, int lower =0, int delta = ) 

Creates an array with an upper bound of upper, a lower bound of lower, and 
a growth delta of delta. It requires a < operator for type T. 

TMSArrayAsVectorlterator template arrays.h 

template <class T, class Alloo class TMSArrayAsVectorlterator; 

Implements an iterator object to traverse TMSArrayAsVector objects. See 
TMArr ay AsVectorlterator on page 301 for members. 

Public constructors 

Constructor TMSArrayAsVectorlterator ( const TMSArrayAsVector<T> & a ) 

Creates an iterator object to traverse TS Array AsVector objects. 

TSArray template arrays.h 

A simplified name for TSArray AsVector. 
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TSArrayAsVector template arrays.h 

template <class T> class TSArrayAsVector; 

Implements a sorted array of objects of type T, using a vector as the 
underlying implementation. With the exception of the AddAt member 
function, TSArrayAsVector inherits its member functions and operators 
from TMArrayAsVector. See TMArrayAsVector on page 297 for members. 

Public constructors 

Constructor TSArrayAsVector ( int upper, int lower = 0, int delta = ) 

Creates an array with an upper bound of upper, a lower bound of lower, and 
a growth delta of delta. It requires a < operator for type T. 

TSArrayAsVectorlterator template arrays.h 

template <class T> class TSArrayAsVectorlterator; 

Implements an iterator object to traverse TSArrayAsVector objects. See 
TMArrayAsVectorlterator on page 301 for members. 



Public constructors 



Constructor 



TSArrayAsVectorlterator ( const TSArrayAsVector<T> & a ) : 
Creates an iterator object to traverse TSArrayAsVector objects. 



TSArraylterator template arrays.h 

A simplified name for TSArrayAsVectorlterator. 

TISArrayAsVector template arrays.h 

template <class T> class TISArrayAsVector; 

Implements an indirect sorted array of objects of type T, using a vector as 
the underlying implementation. See TMIArrayAsVector on page 302 for 
members. 
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Public constructors 



Constructor TISArrayAsVector( int upper, int lower =0, int delta = ) 

Creates an indirect array with an upper bound of upper, a lower bound of 
lower, and a growth delta of delta. 

TISArrayAsVectorlterator template arrays.h 

template <class T> class TISArrayAsVectorlterator; 

Implements an iterator object to traverse TIS Array 'AsVector objects. See 
TMArrayAsVectorlterator on page 301 for members. 



Public constructors 



Constructor 



TISArrayAsVectorlterator! const TISArrayAsVector<T> &a ) 
Creates an iterator object to traverse TISArrayAsVector objects. 



TMISArrayAsVector template arrays.h 

template <class T, class Alloo class TMISArrayAsVector; 

Implements a managed, indirect sorted array of objects of type T, using a 
vector as the underlying implementation. See TMI Array AsVector on page 
302 for members. 

Public constructors 

Constructor TMISArrayAsVector ( int upper, int lower = 0, int delta = ) 

Creates an indirect array with an upper bound of upper, a lower bound of 
lower, and a growth delta of delta. 

TMDDAssociation template assoc.h 

template <class K, class V, class A> class TMDDAssociation; 
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Implements a managed association, binding a direct key (K) with a direct 
value (V) . Assumes that K has a HashValue member function, or that a 
global function with one of the following prototypes exists: 

unsigned HashValue ( K ); 
unsigned HashValue ( K & ) ; 
unsigned HashValue ( const K & ); 

K also must have a valid == operator. Class A represents the user-supplied 
storage manager. 

Public constructors 

Constructor TMDDAssociationO 

The default constructor. 

Constructor TMDDAssociation( const K &k, const V &v ) 

Constructs an object that associates a copy of key object k with a copy of 
value object v. 

Public member functions 

DeleteElementS vo id DeleteElements ( ) 

The dictionary containing the associations determines whether pointed-to 
objects should be deleted, and if so, calls DeleteElements for each of the 
associations it holds. 



HashValue 


unsigned HashValue () 




Returns the hash value for the key. 


Key 


const K& Key() 




Returns KeyData. 


Value 


const V& Value () const; 




Returns ValueData. 



Operators 



operator == 



Tests equality between keys. 
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TDDAssociation template 



assoc.h 



template <class K, class V> class TDDAssociation; 

Standard association (direct key, direct value). Implements an association, 
binding a direct key (K) with a direct value (V). Assumes that K has a 
HashValue member function, or that a global function with the following 
prototype exists: 

unsigned HashValue ( K & ) ; 

K also must have a valid == operator. See TMDD 'Association on page 310 for 
members. 



Public constructors 



Constructor 



Constructor 



TDDAssociation () 

The default constructor. 

TDDAssociation ( const K &k, const V &v ) 

Constructs an object that associates key object k with value object v. 



TMDIAssociation template 



assoc.h 



template <class K, class V, class A> class TMDIAssociation; 

Implements a managed association, binding a direct key (K) with a indirect 
value (V) . Assumes that K has a HashValue member function, or that a 
global function with the following prototype exists: 

unsigned HashValue ( K & ) ; 

K also must have a valid == operator. Class A represents the user-supplied 
storage manager. 

Public constructors 



Constructor 



Constructor 



TMDIAssociation () 

The default constructor. 

TMDIAssociation ( const K& k, V * v ) 

Constructs an object that associates key object k with value object v. 
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Public member functions 



HashValue 


unsigned HashValue () 




Returns the hash value for the key. 


Key 


const K& Key() 




Returns the key. 


Value 


const V * Value () 




Returns a pointer to the data. 



Operators 



operator == i n t operator == (const TMDDAssociation<K,V,A> & a) 

Tests the equality between keys. 



TDIAssociation template 



assoc.h 



template <class K, class V> class TDIAssociation; 

Implements an association, binding a direct key (K) with a indirect value 
(V). Assumes that K has a HashValue member function, or that a global 
function with the following prototype exists: 

unsigned HashValue ( K & ) ; 

K also must have a valid == operator. See TMDIAssociation on page 312 for 
members. 

Public constructors 

Constructor TDIAssociation () 

The default constructor. 
Constructor TDIAssociation ( const K& k, V * v ) 

Constructs an object that associates key object k with value object v. 

unsigned HashValue (int& i) { return i; } 

TDIAssociation<int, int> assoc( 3, new int (4) ) /* Create an association */ 

TDictionaryAsHashTable<TDIAssociation<int, int> > diet; /* Creates a 

dictionary */ 
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dict.Add( assoc ); /* Copies assoc into the dictionary */ 
dict.OwnsElementsO ; /* Tell diet that it should delete pointed-to objects */ 
diet. Flush; /* Deletes the int created by new in the first line */ 



TMIDAssociation template 



assoc.h 



template <class K, class V, class A> class TMIDAssociation; 

Implements a managed association, binding an indirect key (K) with a 
direct value (V) . Assumes that K has a HashValue member function, or that 
a global function with the following prototype exists: 

unsigned HashValue ( K & ); 

K also must have a valid == operator. Class A represents the user-supplied 
storage manager. 



KeyData 
ValueData 



Protected data members 



K KeyData; 

The key class passed into the template by the user. 

V ValueData; 

The value class passed into the template by the user. 



Public constructors 



Constructor 



Constructor 



TMIDAssociation () 

The default constructor. 

TMIDAssociation ( K *k, const V& v ) 

Constructs an object that associates key object k with value object v. 



Public member functions 



DeleteElements 



HashValue 



void DeleteElements () 

The dictionary containing the associations determines whether pointed-to 
objects should be deleted, and if so, calls DeleteElements for each of the 
associations it holds. 

unsigned HashValue () 
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Returns the hash value for the key. 
Key const K * Key() 

Returns a pointer to the key. 
Value const V& Valued const; 

Returns a copy of the data. 

Operators 



operator == j_ n t operator == (const TMIDAssociation<K,V,A> & a) 

Tests the equality between keys. 

TIDAssociation template assoc.h 

template <class K, class V> class TIDAssociation; 

Implements an association, binding an indirect key (X) with a direct value 
(V) . Assumes that K has a HashValue member function, or that a global 
function with the following prototype exists: 

unsigned HashValue ( K & ) ; 

K also must have a valid == operator. See TMIDAssociation on page 314 for 
members. 



Public constructors 



Constructor TIDAssociation () 

The default constructor. 
Constructor TIDAssociation ( K * k, const V& v ) 

Constructs an object that associates key object *k with value object v. 

TMIIAssociation template assoc.h 

template <class K, class V, class A> class TMIIAssociation; 

Implements a managed association, binding an indirect key (K) with an 
indirect value (V) . Assumes that K has a HashValue member function, or 
that a global function with the following prototype exists: 
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unsigned HashValue( K & ) ; 

K also must have a valid == operator. Class A represents the user-supplied 
storage manager. 

Public constructors 



Constructor 



Constructor 



TMIIAssociationO * 

The default constructor. 

TMIIAssociation( K * k, V * v ) 

Constructs an object that associates key object *k with value object *v. 



Public member functions 



DeleteElementS vo id DeleteElementsO 

The dictionary containing the associations determines whether pointed-to 
objects should be deleted, and if so, calls DeleteElementS for each of the 
associations it holds. 



HashValue 


unsigned HashValue () 




Returns the hash value for the key. 


Key 


const K * KeyO 




Returns a pointer to the key. 


Value 


const V * Value () 




Returns a pointer to the data. 



Operators 



operator == i n t operator == (const TMIIAssociation<K,V,A> & a) 

Tests equality between keys. 



TIIAssociation template 



assoc.h 



template <class K, class V> class TIIAssociation; 

Standard association (indirect key, indirect value). Implements an 
association, binding an indirect key (K) with an indirect value (V) . 
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Assumes that K has a HashValue member function, or that a global function 
with the following prototype exists: 

unsigned HashValue ( K & ); 

K also must have a valid == operator. See TMIIAssociation on page 315 for 
members. 



Public constructors 



Constructor 



Constructor 



TIIAssociation() 

The default constructor. 

TIIAssociation( K *k, V * v ) 

Constructs an object that associates key object *k with value object *v. 



TMBagAsVector template 



bags.h 



template <class T, class Alloo class TMBagAsVector; 

Implements a managed bag of objects of type T, using a vector as the 
underlying implementation. Bags, unlike sets, can contain duplicate objects. 



CondFunc 



IterFunc 



Type definitions 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public constructors 



Constructor TMBagAsVector ( unsigned sz = DEFAULT_BAG_SIZE ) 

Constructs a managed, empty bag. sz represents the number of items the 
bag can hold. 
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Public member functions 



Add 



int Add( const T& t ) 

Adds the given object to the bag. 

int Detach ( const T& t); 
Removes the specified object. 

See also: TShouldDelete::ownsElements 

T* Find( const T& t ) const; 

Returns a pointer to the given object if found; otherwise returns 0. 

void Flush () 

Removes all the elements from the bag without destroying the bag. 

See also: Detach 

void ForEach(IterFunc iter, void *args ) 

ForEach executes the given function iter for each element in the bag. The 
args argument lets you pass arbitrary data to this function. 

GetltemslnContainer i nt GetltemsInContainerO const; 

Returns the number of objects in the bag. 

int HasMember( const T& t ) const; 

Returns 1 if the given object is found; otherwise returns 0. 

int isEmptyO const; 

Returns 1 if the bag is empty; otherwise returns 0. 

int isFull() const; 

Returns 0. 



Detach 



Find 



Flush 



ForEach 



HasMember 



IsEmpty 



IsFull 



TMBagAsVectorlterator template 



bags.h 



template <class T, class Alloo class TMBagAsVectorlterator; 

Implements an iterator object to traverse TMBagAsVector objects. See 
TMArrayAsVectorlterator on page 301 for members. 
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Public constructors 



Constructor TMBagAsVectorIterator( const TMBagAsVector<T,Alloc> & b ) 

Constructs an object that iterates on TMBagAsVector objects. 

TBagAsVector template bags.h 

template <class T> class TBagAsVector; 

Implements a bag of objects of type T, using a vector as the underlying 
implementation. TStandardAllocator is used to manage memory. See 
TMBagAsVector on page 317 for members. 

Public constructors 

Constructor TBagAsVector ( unsigned sz = DEFAULT_BAG_SIZE ) 

Constructs an empty bag. sz represents the number of items the bag can 
hold. 

TBagAsVectorlterator template bags.h 

template <class T> class TBagAsVectorlterator; 

Implements an iterator object to traverse TBagAsVector objects. 
TStandardAllocator is used to manage memory. See TMArrayAsVectorlterator 
on page 301 for members. 



Public constructors 



Constructor 



TBagAsVectorlterator ( const TBagAsVector<T> & b ) 
Constructs an object that iterates on TBagAsVector objects. 



TMIBagAsVector template bags.h 

template <class T, class Alloo class TMIBagAsVector; 

Implements a managed bag of pointers to objects of type T, using a vector 
as the underlying implementation. 
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Type definitions 



CondFunc 



IterFunc 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public constructors 



Constructor 



TMIBagAsVector ( unsigned sz = DEFAULT_BAG_SIZE ) 

Constructs an empty, managed, indirect bag. sz represents the initial 
number of slots allocated. 



Public member functions 



Add 



Detach 



Find 



FirstThat 



Flush 



int Add( T *t ) 

Adds the given object pointer to the bag. 

int Detach ( T *t, DeleteType dt = NoDelete ) 

Removes the specified object pointer. The value of dt and the current 
ownership setting determine whether the object itself will be deleted. 
DeleteType is defined in the base class TShouldDelete as enum { , NoDelete, 
Def Delete , Delete } . The default value of dt, NoDelete, means that the object 
will not be deleted regardless of ownership. With dt set to Delete, the object 
will be deleted regardless of ownership. If dt is set to DefDelete, the object 
will only be deleted if the bag owns its elements. 

See also: TShouldDelete: :ownsElements 

T *Find( T *t ) const; 

Returns a pointer to the object if found; otherwise returns 0. 

T *FirstThat( CondFunc cond, void *args ) const; 
See: TMBagAsVector::FirstThat 

void Flush ( TShouldDelete: : DeleteType dt = TShouldDelete: : DefDelete ) 

Removes all the elements from the bag without destroying the bag. The 
value of dt determines whether the elements themselves are destroyed. By 
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default, the ownership status of the bag determines their fate, as explained 
in the Detach member function. You can also set dt to Delete and NoDelete. 

See also: Detach 

ForEach vo ici ForEachdterFunc iter, void *args ) 

ForEach executes the given function iter for each element in the bag. The 
args argument lets you pass arbitrary data to this function. 

GetltemslnContainer i nt GetltemsInContainerO const; 

Returns the number of objects in the bag. 
HasMember i nt HasMember( const T& t ) const; 

Returns 1 if the given object is found; otherwise returns 0. 
IsEmpty int isEmptyO const; 

Returns 1 if the bag is empty; otherwise returns 0. 
IsFull int isFulK) const; 

Returns 0. 

LastThat t *LastThat(CondFunc cond, void *args ) const; 

Returns a pointer to the last object in the bag that satisfies a given 
condition. You supply a test function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 

TMIBagAsVectorlterator template bags.h 

template <class T, class Alloo class TMIBagAsVectorlterator; 

Implements an iterator object to traverse TMIBagAsVector objects. See 
TMArrayAsVectorlterator on page 301 for members. 

Public constructors 

Constructor TMIBagAsVectorlterator ( const TMIBagAsVector<T, Alloo & s ) 

Constructs an object that iterates on TMIBagAsVector objects. 
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TIBagAsVector template bags.h 

template <class T> class TIBagAsVector; 

Implements a bag of pointers to objects of type T, using a vector as the 
underlying implementation. TStandardAllocator is used to manage memory. 
See TMIBagAsVector on page 319 for members. 

Public constructors 

Constructor TIBagAsVector ( unsigned sz = DEFAULT_BAG_SIZE ) 

Constructs an empty, managed, indirect bag. sz represents the initial 
number of slots allocated. 

TIBagAsVectorlterator template bags.h 

template <class T> class TIBagAsVectorlterator; 

Implements an iterator object to traverse TIBagAsVector objects. 
TStandardAllocator is used to manage memory. See TMArrayAsVectorlterator 
on page 301 for members. 

Public constructors 

Constructor TIBagAsVectorlterator ( const TIBagAsVector<T> & s ) 

Constructs an object that iterates on TMIBagAsVector objects. 

TBinarySearchTreelmp template binimp.h 

template <class T> class TBinarySearchTreelmp; 

Implements an unbalanced binary tree. Class T must have < and == 
operators, and must have a default constructor. 

Public member functions 

Add int Add( const T& t ) 

Creates a new binary-tree node and inserts a copy of object t into it. 
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int Detach ( const T& t ) 

Removes the node containing item t from the tree. 

T * Find( const T& t ) const; 

Returns a pointer to the node containing item t . 

void Flush () ; 

Removes all items from the tree. 

void ForEachf IterFunc iter, void * args, IteratorOrder order = InOrder ) 

Creates an internal iterator that executes the given function iter for each 
item in the container. The args argument lets you pass arbitrary data to this 
function. 

GetltemslnContainer unsigned GetltemsInContainerd; 

Returns the number of items in the tree. 
Parent::lsEmpty i nt isEmptyO; 

Returns 1 if the tree is empty; otherwise returns 0. 



Detach 



Find 



Flush 



ForEach 



Protected member functions 



EqualTo virtual int EqualTo( BinNode *nl, BinNode *n2 ) 

Tests the equality between two nodes. 

LessThan virtual int LessThan( BinNode *nl, BinNode *n2 ) 

Tests if node nl is less than node n2. 

DeleteNode virtual void DeleteNode( BinNode *node, int del) 

Deletes node. The second parameter is ignored. 



TBinarySearchTreelteratorlmp template 



binimp.h 



template <class T> class TBinarySearchTreelteratorlmp; 
Implements an iterator that traverses TBinarySearchTreelmp objects. 
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Public constructors 



Constructor TBinarySearchTreelteratorlmpt TBinarySearchTreeImp<T>& tree, 

TBinarySearchTreeBase : : IteratorOrder 
order = TBinarySearchTreeBase: -.InOrder 

Constructs an iterator object that traverses a TBinarySearchTreelmp 
container. 



Public member functions 



Current 



Restart 



const T& Current () const;. 

Returns the current object. 

void Restart () 

Restarts iteration from the beginning of the tree. 



Operators 



operator int operator int() const; 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 

operator ++ const t& operator ++ ( int ) 

Moves to the next object in the tree, and returns the object that was current 
before the move (post-increment). 

const T& operator ++ () 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 



TIBinarySearchTreelmp template 



binimp.h 



template <class T> class TIBinarySearchTreelmp; 

Implements an indirect unbalanced binary tree. Class T must have < and == 
operators, and must have a default constructor. 
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Public member functions 



Add 



Detach 



Find 



int Add( T * t ) 

Creates a new binary-tree node and inserts a pointer to object t into the tree. 

int Detach ( T * t, int del = ) 

Removes the node containing item t from the tree. The item is deleted if del 
isl. 



T * Find( T * t ) const; 

Returns a pointer to the node containing *t. 

Flush void Flush (int del=0) ; 

Removes all items from the tree. The are deleted if del is 1. If del is the 
items are not deleted. 

ForEach vo id ForEach( IterFunc iter, void * args, IteratorOrder order = InOrder ) 

Creates an internal iterator that executes the given function iter for each 
item in the container. The args argument lets you pass arbitrary data to this 
function. 

GetltemslnContainer unsigned GetltemsInContainerO ; 

Returns the number of items in the tree. 
Parent::lsEmpty i nt i S Empty() ; 

Returns 1 if the tree is empty; otherwise returns 0. 



Protected member functions 



EqualTo 



LessThan 



DeleteNode 



virtual int EqualTo ( BinNode *nl, BinNode *n2 ) 

Tests the equality between two nodes. 

virtual int LessThan ( BinNode *nl, BinNode *n2 ) 

Tests if node nl is less than node n2. 

virtual void DeleteNode ( BinNode *node, int del) 

Deletes node. The second parameter is ignored. 
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TIBinarySearchTreelteratorlmp template 



binimp.h 



template <class T> class TIBinarySearchTreelteratorlmp; 
Implements an iterator that traverses TIBinarySearchTreelmp objects. 

Public constructors 

Constructor TIBinarySearchTreelteratorlmp ( TIBinarySearchTreeImp<T>& tree, 
TBinarySearchTreeBase: :IteratorOrder order = 
TBinarySearchTreeBase: :InOrder ) : 
TBinarySearchTreeIteratorImp<TVoidPointer> (tree, order) 

Constructs an iterator object that traverses a TIBinarySearchTreelmp 
container. 

Public member functions 



Current 



Restart 



T *Current() const; 

Returns a pointer to the current object. 

void Restart () 

Restarts iteration from the beginning of the tree. 



Operators 



operator int operator int() const; 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 

operator ++ T Operator ++ ( int i ) 

Moves to the next object in the tree, and returns a pointer to the object that 
was current before the move (post-increment). 

T *operator ++ () 
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Moves to the next object, and returns a pointer to the object that was 
current after the move (pre-increment). 



TMDequeAsVector template 



deques.h 



template <class T, class Alloo class TMDequeAsVector; 

Implements a managed dequeue of T objects, using a vector as the 
underlying implementation. 



CondFunc 



IterFunc 



Type definitions 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public constructors 



Constructor 



TMDequeAsVector ( unsigned max = DEFAULT_DEQUE_SIZE 
Constructs a dequeue of max size. 



Public member functions 



FirstThat 



Flush 



ForEach 



T *FirstThat( CondFunc cond, void *args ) const; 

Returns a pointer to the first object in the dequeue that satisfies a given 
condition. You supply a test-function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 

See also: LastThat 

void Flush () 

Flushes the dequeue without destroying it. 

See also: TShouldDelete::ownsElements 

void ForEach (IterFunc iter, void *args ); 
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GetLeft 



Executes function iter for each dequeue element. ForEach executes the given 
function iter for each element in the array. The args argument lets you pass 
arbitrary data to this function. 

GetltemslnContainer i nt GetltemsInContainerO const; 

Returns the number of items in the dequeue. 

T GetLeft (); 

Returns the object at the left end and removes it from the dequeue. The 
debuggable version throws an exception when the dequeue is empty. 

See also: PeekLeft 

T GetRight ( ) ; 

Same as GetLeft, except that the right end of the dequeue is returned. 

See also: PeekRight 

int IsEmptyO const; 

Returns 1 if the dequeue has no elements; otherwise returns 0. 

int IsFullO const; 

Returns 1 if the dequeue is full; otherwise returns 0. 

T *LastThat(CondFunc cond, void *args ) const; 

Returns a pointer to the last object in the dequeue that satisfies a given 
condition. You supply a test function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 



GetRight 



IsEmpty 



IsFull 



LastThat 



PeekLeft 



PeekRight 



PutLeft 



See also: FirstThat, ForEach 

const T& PeekLeft () const; 

Returns the object at the left end (head) of the dequeue. The object stays in 
the dequeue. 

See also: GetLeft 

const T& PeekRight () const; 

Returns the object at the right end (tail) of the dequeue. The object stays in 
the dequeue. 

See also: GetRight 

void PutLeft ( const T& ) ; 

Adds (pushes) the given object at the left end (head) of the dequeue. 
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PutRight void PutRight ( const T& ) ; 

Adds (pushes) the given object at the right end (tail) of the dequeue. 

Protected data members 

Data Vect Data; 

The vector containing the dequeue's data. 
Left unsigned Left; 

Index to the leftmost element of the dequeue. 
Right unsigned Right; 

Index to the rightmost element of the dequeue. 

Protected member functions 

Next unsigned Next( unsigned index ) const; 

Returns index + 1. Wraps around to the head of the dequeue. 

See also: Prev 
" rev unsigned Prev( unsigned index ) const; 

Returns index - 1. Wraps around to the tail of the dequeue. 

TMDequeAsVectorlterator template deques.h 

template <class T, class Alloo class TMDequeAsVectorlterator; 
Implements an iterator object for a managed, vector-based dequeue. 

Public constructors 

Constructor TMDequeAsVectorlterator ( const TMDequeAsVector<T, Alloo &d ) 

Constructs an object that iterates on TMDequeAsVector objects. 

Public member functions 

Current CO nst T& Current ( ) ; 
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Restart 



Returns the current object. 

void Restart () ; 
Restarts iteration. 



Operators 



Operator ++ con st T& operator ++ ( int ) ; 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

const T& operator ++ (); 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 

operator int operator int(); 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. Iterator converts to if nothing remains in the iterator. 



TDequeAsVector template 



deques.h 



template <class T> class TDequeAsVector; 

Implements a dequeue of T objects, using a vector as the underlying 
implementation. T Standard Allocator is used to manage memory. See 
TMDequeAsVector on page 327 for members. 



Public constructors 



Constructor TDequeAsVector ( unsigned max = DEFAULT_DEQUE_SIZE ) 

Constructs a dequeue of max size. 



TDequeAsVectorlterator template 



deques.h 



template <class T> class TDequeAsVectorlterator; 

Implements an iterator object for a vector-based dequeue. See 
TMDequeAsVectorlterator on page 329 for members. 



330 



Borland C++ for OS/2 Library Reference 



Dequeue containers 



Public constructors 



Constructor TDequeAsVectorIterator( const TDequeAsVector<T> &d ) 

Constructs an object that iterates on TMDequeAsVector objects. 



TMIDequeAsVector template 



deques.h 



template <class T, class Alloo class TMIDequeAsVector; 

Implements a managed, indirect dequeue of pointers to objects of type T, 
using a vector as the underlying implementation. 



CondFunc 



IterFunc 



Type definitions 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public constructors 



Constructor TMIDequeAsVector ( unsigned sz = DEFAULT_DEQUE_SIZE 

Constructs an indirect dequeue of max size. 

Public member functions 



FirstThat 



Flush 



T *FirstThat( CondFunc cond, void *args ) const; 

Returns a pointer to the first object in the dequeue that satisfies a given 
condition. You supply a test-function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 

See also: LastThat 

void Flush ( TShouldDelete: :DeleteType = TShouldDelete: :Def Delete ); 

Flushes the dequeue without destroying it. The fate of any objects removed 
depends on the current ownership status and the value of the dt argument. 
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ForEach 



void ForEach (IterFunc iter, void *args 



GetLeft 



Executes function iter for each dequeue element. ForEach executes the given 
function iter for each element in the array. The args argument lets you pass 
arbitrary data to this function. 

GetltemslnContainer i nt GetltemsInContainerO const; 

Returns the number of items in the dequeue. 

T *GetLeft() 

Returns a pointer to the object at the left end and removes it from the 
dequeue. Returns if the dequeue is empty. 

See also: PeekLeft 

T *GetRight() 

Same as GetLeft, except that the right end of the dequeue is returned. 

See also: PeekRight 

int IsEmptyO const; 

Returns 1 if a dequeue has no elements; otherwise returns 0. 

int isFull() const; 

Returns 1 if a dequeue is full; otherwise returns 0. 

T *LastThat (CondFunc cond, void *args ) const; 

Returns a pointer to the last object in the dequeue that satisfies a given 
condition. You supply a test function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 

See also: FirstThat, ForEach 

T *PeekLeft() const; 

Returns a pointer to the object at the left end (head) of the dequeue. The 
object stays in the dequeue. 

See also: GetLeft 

T *PeekRight() const; 

Returns the object at the right end (tail) of the dequeue. The object stays in 
the dequeue. 

See also: GetRight 



GetRight 



IsEmpty 



IsFull 



LastThat 



PeekLeft 



PeekRight 
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PutLeft void PutLeft( T *t ) 

Adds (pushes) the given object pointer at the left end (head) of the 
dequeue. 

PutRight void PutRightf T *t ) 

Adds (pushes) the given object pointer at the right end (tail) of the 
dequeue. 

TMIDequeAsVectorlterator template deques.h 

template <class T, class Alloo class TMIDequeAsVectorlterator; 

Implements an iterator for the family of managed, indirect dequeues 
implemented as vectors. See TMDequeAsVectorlterator on page 329 for 
members. 

Public constructors 

Constructor TMIDequeAsVectorlterator ( const TMIDequeAsVector<T ; Alloo &d ) 

Creates an object that iterates on TMIDequeAsVector objects. 

TIDequeAsVector template deques.h 

template <class T> class TIDequeAsVector; 

Implements an indirect dequeue of pointers to objects of type T, using a 
vector as the underlying implementation. See TMIDequeAsVector on page 
331 for members. 

Public constructors 

Constructor TIDequeAsVector ( unsigned sz = DEFAULT_DEQUE_SIZE ) : 

TMIDequeAsVector<T, TStandardAllocator> ( sz ) 

Constructs an indirect dequeue of max size. 
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TIDequeAsVectorlterator template 



deques.h 



template <class T> class TIDequeAsVectorlterator; 

Implements an iterator for the family of indirect dequeues implemented as 
vectors. See TMDequeAsVectorlterator on page 329 for members. 



Public constructors 



Constructor 



TIDequeAsVectorlterator ( const TIDequeAsVector<T> &d ) 
Constructs an object that iterates on TIDequeAsVector objects. 



TMDequeAsDoubleList template 



deques.h 



template <class T, class Alloo class TMDequeAsDoubleList; 

Implements a managed dequeue of objects of type T, using a double-linked 
list as the underlying implementation. 



CondFunc 



IterFunc 



Type definitions 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public member functions 



FirstThat 



Flush 



T *FirstThat( CondFunc cond, void *args ) const; 

Returns a pointer to the first object in the dequeue that satisfies a given 
condition. You supply a test-function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 

See also: LastThat 

void Flush () 

Flushes the dequeue without destroying it. 
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ForEach 



void ForEach (IterFunc iter, void *args 



Executes function iter for each dequeue element. ForEach executes the given 
function iter for each element in the array. The args argument lets you pass 
arbitrary data to this function. 

GetltemslnContainer i nt GetltemsInContainerO const; 

Returns the number of items in the dequeue. 

T GetLeftO 

Returns the object at the left end and removes it from the dequeue. 

T GetRightO 

Same as GetLeft, except that the right end of the dequeue is returned. 

See also: PeekRight 

int IsEmptyO const; 

Returns 1 if a dequeue has no elements; otherwise returns 0. 

int IsFullO const; 

Returns 1 if a dequeue is full; otherwise returns 0. 

T *LastThat (CondFunc cond, void *args ) const; 

Returns a pointer to the last object in the dequeue that satisfies a given 
condition. You supply a test function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 



GetLeft 



GetRight 



IsEmpty 



IsFull 



LastThat 



PeekLeft 



PeekRight 



PutLeft 



See also: FirstThat, ForEach 

const T& PeekLeft () const; 

Returns a reference to the object at the left end (head) of the dequeue. The 
object stays in the dequeue. 

See also: GetLeft 

const T& PeekRight () const; 

Returns a reference to the object at the right end (tail) of the dequeue. The 
object stays in the dequeue. 

See also: GetRight 

void PutLeft ( const T& t ) 

Adds (pushes) the given object at the left end (head) of the dequeue. 
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PutRight void PutRightt const T& t ) 

Adds (pushes) the given object at the right end (tail) of the dequeue. 

TMDequeAsDoubleListlterator template deques.h 

template <class T, class Alloo class TMDequeAsDoubleListlterator; 

Implements an iterator object for a double-list based deques. See 
TMDoubleListlteratorlmp on page 348 for members. 

Public constructors 

Constructor TMDequeAsDoubleListlterator ( const TMDequeAsDoubleList<T, Alloo & s ) 

Constructs an object that iterates on TMDequeAsDoubleList objects. 

TDequeAsDoubleList template deques.h 

template <class T> class TDequeAsDoubleList; 

Implements a dequeue of objects of type T, using a double-linked list as the 
underlying implementation, and TStandardAllocator as its memory manager. 
See TMDequeAsDoubleList on page 334 for members. 

TDequeAsDoubleListlterator template deques.h 

Implements an iterator object for a double-list based dequeue. 

Public constructors 

Constructor TMDequeAsDoubleListlterator! const TMDequeAsDoubleList<T, Alloo & s ) 

Constructs an object that iterates on TDequeAsDoubleList objects. 

TMIDequeAsDoubleList template deques.h 

template <class T, class Alloo class TMIDequeAsDoubleList; 
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CondFunc 



IterFunc 



FirstThat 



Flush 



ForEach 



Implements a managed dequeue of pointers to objects of type T, using a 
double-linked list as the underlying implementation. 

Type definitions 

typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 

Public member functions 

T *FirstThat( CondFunc cond, void *args ) const; 

Returns a pointer to the first object in the dequeue that satisfies a given 
condition. You supply a test-function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 

See also: LastThat 

void Flush ( TShouldDelete: :DeleteType dt = TShouldDelete: :Def Delete ) 

Flushes the dequeue without destroying it. The fate of any objects removed 
depends on the current ownership status and the value of the dt argument. 



void ForEach (IterFunc iter, void *args ) 

Executes function iter for each dequeue element. ForEach executes the given 
function iter for each element in the array. The args argument lets you pass 
arbitrary data to this function. 

GetltemslnContainer i nt GetltemsInContainerf) const; 

Returns the number of items in the dequeue. 

GetLeft t *GetLeft() 

Returns a pointer to the object at the left end and removes it from the 
dequeue. Returns if the dequeue is empty. 

See also: PeekLeft 

GetRight t *GetRight() 
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IsEmpty 



IsFull 



LastThat 



PeekLeft 



PeekRight 



PutLeft 



PutRight 



Same as GetLeft, except that a pointer to the object at the right end of the 
dequeue is returned. 

See also: PeekRight 

int IsEmpty () const; 

Returns 1 if the dequeue has no elements; otherwise returns 0. 

int IsFull () const; 

Returns 1 if the dequeue is full; otherwise returns 0. 

T *LastThat (CondFunc cond, void *args ) const; 

Returns a pointer to the last object in the dequeue that satisfies a given 
condition. You supply a test function pointer, cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 

See also: FirstThat, ForEach 

T *PeekLeft() const; 

Returns a pointer to the object at the left end (head) of the dequeue. The 
object stays in the dequeue. 

T *PeekRight() const; 

Returns the object at the right end (tail) of the dequeue. The object stays in 
the dequeue. 

void PutLeft ( T *t ) 

Adds (pushes) the given object pointer at the left end (head) of the 
dequeue. 

void PutRight ( T *t ) 

Adds (pushes) the given object pointer at the right end (tail) of the 
dequeue. 



TMIDequeAsDoubleListlterator template 



deques.h 



template <class T, class Alloo class TMIDequeAsDoubleListlterator; 

Implements an iterator for the family of managed, indirect dequeues 
implemented as double lists. See TMDoubleListlteratorlmp on page 348 for 
members. 
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Public constructors 



Constructor TMIDequeAsDoubleListIterator( const TMIDequeAsDoubleList<T,Alloc> s ) 

Constructs an object that iterates on TMIDequeAsDoubleList objects. 

TIDequeAsDoubleList template deques.h 

template <class T> class TIDequeAsDoubleList; 

Implements a dequeue of pointers to objects of type T, using a double- 
linked list as the underlying implementation. See TMIDequeAsDoubleList on 
page 336 for members. 

TIDequeAsDoubleListlterator template deques.h 

template <class T> class TIDequeAsDoubleListlterator; 

Implements an iterator for the family of indirect dequeues implemented as 
double lists. See TMDoubleListlteratorlmp on page 348 for members. 

Public constructors 

Constructor TIDequeAsDoubleListlterator ( const TIDequeAsDoubleList<T> & s ) 

Constructs an object that iterates on TIDequeAsDoubleList objects. 

TMDictionaryAsHashTable template dict.h 

template <class T, class A> class TMDictionaryAsHashTable; 

Implements a managed dictionary using a hash table as the underlying 
FDS, and using the user-supplied storage allocator A. It assumes that T is 
one of the four types of associations, and that T has meaningful copy and 
== semantics as well as a default constructor. 

Protected data members 

HashTable TMHashTableImp<T,A> HashTable; 

Implements the underlying hash table. 
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Constructor 



Public constructors 



TMDictionaryAsHashTable( unsigned size = DEFAULT_HASH_TABLE_SIZE 
Constructs a dictionary with the specified size. 



Public member functions 



Add 



Detach 



Find 



Flush 



ForEach 



int Add( const T& t ) 

Adds item t if not already in the dictionary. 

int Detach ( const T& t, DeleteType dt = Def Delete ) 

Removes item t from the dictionary. Calls DeleteElements on the association. 

T * Find( constTk t ) 
Returns a pointer to item t . 

void Flush ( DeleteType dt = Def Delete ) 

Removes all items from the dictionary. Calls DeleteElements on the 
association. 



void ForEach ( IterFunc iter, void * args ) 

Creates an internal iterator that executes the given function iter for each 
item in the container. The args argument lets you pass arbitrary data to this 
function. 

GetltemslnContainer inline unsigned GetltemsInContainerO 

Returns the number of items in the dictionary. 
IsEmpty inline int IsEmptyO 

Returns 1 if the dictionary is empty; otherwise returns 0. 



TMDictionaryAsHashTablelterator template 



dict.h 



template <class T, class A> class TMDictionaryAsHashTablelterator; 

Implements an iterator that traverses TMDictionaryAsHashTable objects, 
using the user-supplied storage allocator A. 
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Public constructors 



Constructor 



TMDictionaryAsHashTableIterator(TMDictionaryAsHashTable<T,A> & t ) 

Constructs an iterator object that traverses a TMDictionaryAsHashTable 
container. 



Public member functions 



Current 



Restart 



const T& Current () 

Returns the current object. 

void Restart () ; 

Restarts iteration from the beginning of the dictionary. 



Operators 



operator int operator into 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 

Operator ++ CO nst T& operator ++ (int) 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

const T& operator ++ () 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 



TDictionaryAsHashTable template 



dict.h 



template <class' T> class TDictionaryAsHashTable; 

Implements a dictionary objects of type T, using the system storage 
allocator T Standard Allocator. It assumes that T is one of the four types of 
associations, and that T has meaningful copy and == semantics as well as a 
default constructor. See TMDictionaryAsHashTable on page 339 for 
members. 
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Public constructors 



Constructor TDictionaryAsHashTable ( unsigned size = DEFAULT_HASH_TABLE_SIZE ) 

Constructs a dictionary with the specified size. 

TDictionaryAsHashTablelterator template dict.h 

template <class T> class TDictionaryAsHashTablelterator; 

Implements an iterator that traverses TDictionaryAsHashTable objects, using 
the system storage allocator TStandardAllocator. 

Public constructors 

Constructor TDictionaryAsHashTablelterator ( TDictionaryAsHashTable<T> & t ) 

Constructs an iterator object that traverses a TDictionaryAsHashTable 
container. 

TMIDictionaryAsHashTable template dict.h 

template <class T, class A> class TMIDictionaryAsHashTable; 

Implements a managed indirect dictionary using a hash table as the 
underlying FDS, and using the user-supplied storage allocator A. It 
assumes that T is of class TAssociation. 

Public constructors 

Constructor TMIDictionaryAsHashTable ( unsigned size = DEFAULT_HASH_TABLE_SIZE ) 

Constructs an indirect dictionary with the specified size. 

Public member functions 

Add i n t Add( T * t ) 

Adds a pointer to item t if not already in the dictionary. 
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Detach int Detach ( T * t, int del = ) 

Removes the pointer to item t from the dictionary, and deletes if del is 1. If 
del is the item is not deleted. 

T * Find( T * t ) 

Returns a pointer to item t. 

void Flush ( int del = ) 

Removes all items from the dictionary. The item is deleted if del is 1. If del is 
the item is not deleted. 

void ForEach( IterFunc iter, void * args ); 

Creates an internal iterator that executes the given function iter for each 
item in the container. The args argument lets you pass arbitrary data to this 
function. 

GetltemslnContainer inline unsigned GetltemsInContainerO 

Returns the number of items in the dictionary. 
IsEmpty inline int isEmptyO 

Returns 1 if the dictionary is empty; otherwise returns 0. 



Find 



Flush 



ForEach 



TMlDictionaryAsHashTablelterator template 



dict.h 



template <class T, class A> class TMIDictionaryAsHashTablelterator; 

Implements an iterator that traverses TMIDictionaryAsHashTable objects, 
using the user-supplied storage allocator A. 

Public constructors 

Constructor TMIDictionaryAsHashTableIterator( TMIDictionaryAsHashTable<T,A> & t ) 

Constructs an iterator object that traverses a TMIDictionaryAsHashTable 
container. 



Public member functions 



Current 



T *Current i 
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Restart 



Returns a pointer to the current object. 

void Restart () ; 

Restarts iteration from the beginning of the dictionary. 



Operators 



operator int operator int() 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 

operator ++ T Operator ++ (int) 

Moves to the next object, and returns a pointer to the object that was 
current before the move (post-increment). 

T *operator ++ 

Moves to the next object, and returns a pointer to the object that was 
current after the move (pre-increment). 



TIDictionaryAsHashTable template 



dict.h 



template <class T> class TIDictionaryAsHashTable; 

Implements an indirect dictionary using a hash table as the underlying 
FDS, and using the system storage allocator TStandardAllocator. It assumes 
that T is one of the four types of associations. See 
TMIDictionaryAsHashTable on page 342 for members. 

Public constructors 

Constructor TIDictionaryAsHashTable ( unsigned size = DEFAULT_HASH_TABLE_SIZE ) 

Constructs an indirect dictionary with the specified size. 



TIDictionaryAsHashTablelterator template 



dict.h 



template <class T> class TIDictionaryAsHashTablelterator; 

Implements an iterator that traverses TIDictionaryAsHashTable objects, 
using the user-supplied storage allocator A. See 
TMIDictionaryAsHashTablelterator on page 343 for members. 
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Public constructors 



Constructor TIDictionaryAsHashTableIterator( TIDictionaryAsHashTable<T> & t ) 

Constructs an iterator object that traverses a TIDictionaryAsHashTable 
container. 

TDictionary template dict.h 

A simplified name for TDictionary AsHashT able. See TDictionary AsHashT able 
on page 341 for members. 

TDictionarylterator template dict.h 

A simplified name for TDictionary AsHashTablelterator. See 
TDictionary AsHashT ablelterator on page 342 for members. 

Public constructors 



Constructor 



TDictionarylterator ( const TDictionary<T> & a ) 

Constructs an iterator object that traverses a TDictionary container. 



TMDoubleListElement template dlistimp.h 

template <class T, class Alloo class TMDoubleListElement; 

This class defines the nodes for double-list classes TMDoubleListlmp and 
TMIDoubleListlmp. 

Public data members 

data T data; 

Data object contained in the double list. 

Next TMDoubleListElement<T> *Next; 

A pointer to the next element in the double list. 

Prev TMDoubleListElement<T> *Prev; 
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A pointer to the previous element in the double list. 

Public constructors 

Constructor TMDoubleListElement ( ) ; 

Constructs a double-list element. 

Constructor TMDoubleListElement ( T& t, TMDoubleListElement<T> *p ) 

Constructs a double-list element, and inserts after the object pointed 
to by p. 



operator delete 
operator new 



Operators 



void operator delete ( void * ); 
Deletes an object. 

void * operator new( size_t sz ) ; 

Allocates a memory block of sz amount, and returns a pointer to the 
memory block. 



TMDoubleListlmp template 



dlistimp.h 



template <class T, class Alloo class TMDoubleListlmp; 

Implements a managed, double-linked list of objects of type T. Assumes 
that T has meaningful copy semantics, operator ==, and a default 
constructor. The memory manager Alloc provides class-specific new and 
delete operators. 



CondFunc 



IterFunc 



Type definitions 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 
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Public constructors 



Constructor TMDoubieListimpO 

Constructs an empty, managed, double-linked list. 

Public member functions 



Add 



AddAtHead 



AddAtTail 



Detach 



DetachAtHead 



FirstThat 



Flush 



ForEach 



IsEmpty 



LastThat 



int Add( const T& t ); 

Add the given object at the beginning of the list. 

int AddAtHead ( const T& t ) ; 

Add the given object at the beginning of the list. 

int AddAtTail ( const T& ) ; 

Adds the given object at the end (tail) the list. 

int Detach ( const T& ); 

Removes the first occurrence of the given object encountered by searching 
from the beginning of the list. 

int DetachAtHead ( ) ; 

Removes items from the head of a list without searching for a match. 

T *FirstThat( CondFunc cond, void *args) const; 

Returns a pointer to the first object in the double-list that satisfies a given 
condition. You supply a test-function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 

void Flush ( ) ; 

Removes all elements from the list without destroying the list. 

void ForEach (IterFunc iter, void *args ); 

ForEach executes the given function iter for each element in the array. The 
args argument lets you pass arbitrary data to this function. 

int IsEmpty () const; 

Returns 1 if array contains no elements; otherwise returns 0. 

T *LastThat( CondFunc cond, void *args ) const; 

Returns a pointer to the last object in the double list that satisfies a given 
condition. You supply a test function pointer cond that returns true for a 
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PeekHead 



PeekTail 



certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 

See also: FirstThat, ForEach 

const T& PeekHead () const; 

Returns a reference to the Head item in the double list, without removing it. 

const T& PeekTail () const; 

Returns a reference to the Tail item in the double list, without removing it. 



Protected data members 



Headjail 



TMDoubleListElement<T> Head, Tail; 

The head and tail items of the double list. 



Protected member functions 



FindDetach 



FindPred 



virtual TMDoubleListElement<T> *FindDetach( const T& t ) 

Determines whether an object is in the list, and returns a pointer to its 
predecessor. Returns if not found. 

virtual TMDoubleListElement<T> *FindPred( const T& ); 

Finds the element that would be followed by the parameter. The function 
does not check whether the parameter is actually there. This can be used for 
inserting (insert after returned element pointer). 



TMDoubleListlteratorlmp template 



dlistimp.h 



template <class T, class Alloo class TMDoubleListlterator; 

Implements a double list iterator. This iterator works with any direct 
double-linked list. For indirect lists, see TMIDoubleListlteratorlmp on 
page 354. 



Public constructors 



Constructor 



TMDoubleListlteratorlmp ( const TMDoubleListImp<T, Alloo &1 ) 
Constructs an iterator that traverses TMDoubleListlmp objects. 
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TMDoubleListIteratorImp( const TMSDoubleListImp<T, Alloo &1 
Constructs an iterator that traverses TMDoubleListlmp objects. 



Current 
Restart 



Public member functions 



const T& Current () 

Returns the current object. 

void Restart!) 

Restarts iteration from the beginning of the list. 



operator int 



operator ++ 



operator — 



Operators 



operator int ( ) 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 

const T& operator ++ ( int ) 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

const T& operator ++ () 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 



const T& operator 



int 



Moves to the previous object, and returns the object that was current before 
the move (post-decrement). 

const T& operator -- () 

Moves to the previous object, and returns the object that was current after 
the move (pre-decrement). 



TDoubleListlmp template 



dlistimp.h 



template <class T> class TDoubleListlmp; 

Implements a double-linked list of objects of type T, using 
TStandardAllocator for memory management. Assumes that T has 
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meaningful copy semantics and a default constructor. See TMDoubleListlmp 
on page 346 for members. 

Public constructors 

Constructor TDoubleListimpO 

Constructs an empty double-linked list. 



TDoubleListlteratorlmp template 



dlistimp.h 



template <class T> class TDoubleListlteratorlmp; 

Implements a double list iterator. This iterator works with any direct 
double-linked list. See TMDoubleListlteratorlmp on page 348 for members. 



Public constructors 



Constructor 



TDoubleListlteratorlmp ( const TDoubleListImp<T> &1 ) 
Constructs an iterator that traverses TDoubleListlmp objects. 



TMSDoubleListlmp template 



dlistimp.h 



template <class T, class Alloo class TMSDoubleListlmp; 

Implements a managed, sorted, double-linked list of objects of type T. It 
assumes that T has meaningful copy semantics, a == operator, a < operator, 
and a default constructor. See TMDoubleListlmp on page 346 for members. 

Protected member functions 

In addition to the following member functions, TMSDoubleListlmp inherits 
member functions from TMDoubleListlmp (see page 346). 

FindDetach virtual TMDoubleListElement<T> *FindDetach( const T& ) ; 

Determines whether an object is in the list, and returns a pointer to its 
predecessor. Returns if not found. 

FindPred virtual TMDoubleListElement<T> *FindPred( const T& ); 
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Finds the element that would be followed by the parameter. The function 
does not check whether the parameter is actually there. This can be used for 
inserting (insert after returned element pointer). 

TMSDoubleListlteratorlmp template dlistimp.h 

template <class T, class Alloo class TMSDoubleListlteratorlmp; 

Implements a double list iterator. This iterator works with any direct 
double-linked list. See TMDoubleListlteratorlmp on page 348 for members. 

Public constructors 

Constructor TMSDoubleListlteratorlmp ( const TMSDoubleListImp<T ; Alloo &1 ) 

Constructs an iterator that traverses TMSDoubleListlmp objects. 

TSDoubleListlmp template dlistimp.h 

template <class T> class TSDoubleListlmp; 

Implements a sorted, double-linked list of objects of type T. It assumes that 
T has meaningful copy semantics, a meaningful < operator, and a default 
constructor. See TMSDoubleListlmp on page 350 for members. 

TSDoubleListlteratorlmp template dlistimp.h 

template <class T> class TSDoubleListlteratorlmp; 

Implements a double list iterator. This iterator works with any direct 
double-linked list. See TMDoubleListlteratorlmp on page 348 for members. 

Public constructors 

Constructor TSDoubleListlteratorlmp ( const TSDoubleListImp<T> &1 ) 

Constructs an iterator that traverses TSDoubleListlmp objects. 
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TMIDoubleListlmp template 



dlistimp.h 



template <classT, class Alloo class TMIDoubleListlmp; 

Implements a managed, double-linked list of pointers to objects of type 
T.The contained objects need a valid == operator. Because pointers always 
have meaningful copy semantics, this class can handle any type of object. 
The memory manager Alloc provides class-specific new and delete 
operators. 



Type definitions 



CondFunc 



IterFunc 



Add 



AddAtHead 



AddAtTail 



Detach 



DetachAtHead 



DetachAtTail 



FirstThat 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 

Public member functions 

int Add( T *t ) 

Adds an object pointer to the double list. 

int AddAtHead ( T *t ); 

Add the given object at the beginning of the list. 

int AddAtTail ( T *t ) 

Adds an object pointer to the tail of the double list. 

int Detach ( T *t, int del = )• 

Removes the given object pointer from the list. The second argument 
specifies whether the object should be deleted. 

int DetachAtHead ( int del = ) 

Deletes the object pointer from the head of the list. 

int DetachAtTail ( int del = ) 

Deletes the object pointer from the tail of the list. 

T *FirstThat ( CondFunc cond, void *args ) const; 
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Returns a pointer to the first object in the double list that satisfies a given 
condition. You supply a test-function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 

See also: LastThat 

Flush vo id Flush ( int = ); 

Removes all elements from the list without destroying the list. 

ForEach vo i(j ForEach(IterFunc iter, void * args ); 

Executes function iter for each double-list element. ForEach executes the 
given function iter for each element in the array. The args argument lets you 
pass arbitrary data to this function. 

GetltemslnContainer unsigned GetltemsInContainerO const; 

Returns the number of items in the array. 

int IsEmptyO const; 

Returns 1 if array contains no elements; otherwise returns 0. 

T *LastThat( CondFunc cond, void *args) const; 

Returns a pointer to the last object in the list that satisfies a given condition. 
You supply a test function pointer cond that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. 



IsEmpty 



LastThat 



PeekHead 



PeekTail 



See also: FirstThat, ForEach 

T *PeekHead() const; 

Returns the object pointer at the Head of the list, without removing it. 

T *PeekTail() const; 

Returns the object pointer at the Tail of the list, without removing it. 



Protected member functions 



FindPred 



virtual TDoubleListElement<void *> *FindPred( void * ); 

Finds the element that would be followed by the parameter. The function 
does not check whether the parameter is actually there. This can be used for 
inserting (insert after returned element pointer). 
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TMIDoubleListlteratorlmp template 



dlistimp.h 



template <class T, class Alloo class TMIDoubleListlteratorlmp; 

Implements a double list iterator. This iterator works with any indirect 
double list. For direct lists, see TMDoubleListlteratorlmp on page 348. 



Public constructors 



Constructor 



TMIDoubleListlteratorlmp ( const TMIDoubleListImp<T, Alloo &1 
Constructs an object that iterates on TIDoubleListlmp objects. 



Public member functions 



Current 



Restart 



T *Current() 

Returns the current object pointer. 

void Restart () 

Restarts iteration from the beginning of the list. 



Operators 



operator ++ T Operator ++ (int) 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

T *operator ++ () 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 



TIDoubleListlmp template 



dlistimp.h 



template <class T> class TIDoubleListlmp; 

Implements a double-linked list of pointers to objects of type T, using 
TStandardAllocator for memory management. Because pointers always have 
meaningful copy semantics, this class can handle any type of object. See 
TMIDoubleListlmp on page 352 for members. 
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TIDoubleListlteratorlmp template dlistimp.h 

template <class T> class TIDoubleListlteratorlmp; 

Implements a double list iterator. This iterator works with any indirect 
double list. See TMIDoubleListlteratorlmp on page 354 for members. 

Public constructors 

Constructor TIDoubleListlteratorlmp ( const TIDoubleListImp<T> &1 ) 

Constructs an object that iterates on TIDoubleListlmp objects. 

TMISDoubleListlmp template dlistimp.h 

template <class T, class Alloo class TMISDoubleListlmp; 

Implements a managed, sorted, double-linked list of pointers to objects of 
type T. Because pointers always have meaningful copy semantics, this class 
can handle any type of object. 

Protected member functions 

In addition to the member function described here, TMISDoubleListlmp 
inherits member functions (see TMIDoubleListlmp on page 352). 

FindDetach virtual TMDoubleListElement<void *> *FindDetach( void * ); 

Determines whether an object is in the list, and returns a pointer to its 
predecessor. 

TMISDoubleListlteratorlmp template dlistimp.h 

template <class T, class Alloo class TMISDoubleListlteratorlmp;- 

Implements a double list iterator. This iterator works with any indirect, 
sorted double list. See TMIDoubleListlteratorlmp on page 354 for members. 

Public constructors 

Constructor TMISDoubleListlteratorlmp ( const TMISDoubleListImp<T, Alloo &1 ) 
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Constructs an object that iterates on TMISDoubleListlmp objects. 

TISDoubleListlmp template dlistimp.h 

template <class T> class TISDoubleListlmp; 

Implements a sorted, double-linked list of pointers to objects of type T, 
using TStandardAllocator for memory management. Because pointers 
always have meaningful copy semantics, this class can handle any type of 
object. See TMIDoubleListlmp on page 352 for members. 

TISDoubleListlteratorlmp template dlistimp.h 

template <class T> class TISDoubleListlteratorlmp; 

Implements a double list iterator. This iterator works with any indirect, 
sorted double list. See TMIDoubleListlteratorlmp on page 354 for members. 

Public constructors 

Constructor TISDoubleListlteratorlmp ( const TISDoubleListImp<T> &1 ) 

Constructs an object that iterates on TMISDoubleListlmp objects. 

TMHashTablelmp template hashimp.h 

template <class T, class Alloo class TMHashTablelmp; 

Implements a managed hash table of objects of type T, using the user- 
supplied storage allocator A. It assumes that T has meaningful copy and == 
semantics, as well as a default constructor. 

Public constructors and destructor 

Constructor TMHashTablelmp ( unsigned aPrime = DEFAULT_HASH_TABLE_SIZE ) 

Constructs a hash table. 
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Public member functions 



Add 



Detach 



Find 



int Add( const T& t ) ; 
Adds item t to the hash table. 

int Detach ( const T& t, int del=0 ); 

Removes item t from the hash table. If del is set to 0, t is deleted; if del is set 
to 1, t is not deleted. 



T * Find( const T& t ) const; 

Returns a pointer to item t . 

Flush vo id Flush () 

Flushes all items in the hash table. The hash table is destroyed if del is 
nonzero. 

ForEach vo id ForEachf IterFunc iter, void *args); 

Creates an internal iterator that executes the given function iter for each 
item in the container. The args argument lets you pass arbitrary data to this 
function. 

GetltemslnContainer unsigned GetltemsInContainerO const; 

Returns the number of items in the hash table. 
IsEmpty i n t isEmptyO const; 

Returns 1 if the hash table is empty; otherwise returns 0. 



TMHashTablelteratorlmp template 



hashimp.h 



template <class T, class Alloo class TMHashTablelteratorlmp; 

Implements an iterator for traversing TMHashTablelmp containers, using 
the user-supplied storage allocator Alloc. 



Public constructors and destructor 



Constructor 



Destructor 



TMHashTablelteratorlmp ( const TMHashTableImp<T,A> & h ) 

Constructs an iterator object that traverses a TMHashTablelmp container. 

-TMHashTablelteratorlmp ( ) 

Destroys the iterator. 
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Public member functions 



Current 



Restart 



const T& Current () 

Returns the current object. 

void Restart ( ) ; 

Restarts iteration from the beginning of the hash table. 



Operators 



operator int operator into 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 

operator ++ con st T& operator ++ (int) 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

const T& operator ++ () 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 



THashTablelmp template 



hashimp.h 



template <class T> class THashTablelmp; 

Implements a hash table of objects of type T, using the system storage 
allocator T Standard Allocator. It assumes that T has meaningful copy and == 
semantics as well as a default constructor. See TMHashTablelmp on page 356 
for members. 



Public constructors 

Constructor THashTablelmp ( unsigned aPrime = DEFAULT_HASH_TABLE_SIZE ) 

Constructs a hash table that uses TStandardAllocator for memory 
management. 
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THashTablelteratorlmp template 



hashimp.h 



template <class T> class THashTablelteratorlmp; 

Implements an iterator for traversing THashTablelmp containers. See 
TMHashTablelteratorlmp on page 357 for members. 



Public constructors 



Constructor 



THashTablelteratorlmp ( const THashTableImp<T,A> & h ) 

Constructs an iterator object that traverses a THashTablelmp container. 



TMIHashTablelmp template 



hashimp.h 



template <class T, class Alloo class TMIHashTablelmp; 

Implements a managed hash table of pointers to objects of type T, using the 
user-supplied storage allocator Alloc. 



Public constructors 



Constructor 



TMIHashTablelmp ( unsigned aPrime = DEFAULT_HASH_TABLE_SIZE 
Constructs an indirect hash table. 



Public member functions 



Add 



Detach 



Find 



Flush 



int Add( T * t ) 

Adds a pointer to item t to the hash table. 

int Detach ( T * t, int del = ) 

Removes a pointer to item t from the hash table, t is deleted if del is set 1, 
and not deleted if del is set to 0. 

T * Find( const T * t ) const; 

Returns a pointer to item t . 

void Flush ( int del = ) 

Flushes all items in the hash table. The hash table is destroyed if del is 
nonzero. 
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ForEach void ForEach( IterFunc iter, void *args) ; 

Creates an internal iterator that executes the given function iter for each 
item in the container. The args argument lets you pass arbitrary data to this 
function. 

GetltemslnContainer unsigned GetltemsInContainerO const; 

Returns the number of items in the hash table. 
IsEmpty int isEmptyO const; 

Returns 1 if the hash table is empty; otherwise returns 0. 



TMIHashTablelteratorlmp template 



hashimp.h 



template <class T, class Alloo class TMIHashTablelteratorlmp; 
Implements an iterator for traversing TMIHashTablelmp containers. 

Public constructors 



Constructor 



TMIHashTablelteratorlmp! const TMIHashTableImp<T,A> & h ) 

Constructs an iterator object that traverses a TMIHashTablelmp container. 



Public member functions 



Current 



Restart 



T *Current() 

Returns a pointer to the current object. 

void Restart () ; 

Restarts iteration from the beginning of the hash table. 



operator int 



operator ++ 



Operators 



operator int() 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 

T *operator ++ (int) 
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Moves to the next object, and returns the object pointer that was current 
before the move (post-increment). 

T *operator ++ () 

Moves to the next object, and returns the object pointer that was current 
after the move (pre-increment). 

TIHashTablelmp template hashimp.h 

template <class T> class TIHashTablelmp; 

Implements a hash table of pointers to objects of type T, using the system 
storage allocator TStandardAllocator. See TMIHashTablelmp on page 359 for 
members. 

Public constructors 

Constructor TIHashTablelmp! unsigned aPrime = DEFAULT_HASH_TABLE_SIZE ) 

Constructs an indirect hash table that uses the system storage allocator. 

TIHashTablelteratorlmp template hashimp.h 

template <class T> class TIHashTablelteratorlmp; 

Implements an iterator object that traverses TIHashTablelmp containers, and 
uses the system memory allocator TStandardAllocator. See 
TMIHashTablelteratorlmp on page 360 for members. 

Public constructors 

Constructor TIHashTablelteratorlmp ( const TIHashTableImp<T> & h ) 

TMListElement template listimp.h 

template <class T, class Alloo class TMListElement; 

This class defines the nodes for TMListlmp and TMIListlmp and related 
classes. 
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Public data members 



data 



Next 



Constructor 



Constructor 



operator delete 
operator new 



T Data; 

Data object contained in the list. 

TMListElement<T,Alloc> *Next; 

A pointer to the next element in the list. 

Public constructors 



TMListElementO ; 

Constructs a list element. 

TMLi st Element ( T& t, TMListElement<T,Alloc> *p ) 

Constructs a list element, and places it after the object at location p. 



Operators 



void operator delete ( void * ) ; 
Deletes an object. 

void *operator new( size_t sz ); 

Allocates a memory block of sz amount, and returns a pointer to the 
memory block. 



TMListlmp template 



listimp.h 



template <class T, class Alloo class TMListlmp; 

Implements a managed list of objects of type T. TMListlmp assumes that T 
has meaningful copy semantics, and a default constructor. 



CondFunc 



IterFunc 



Type definitions 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 
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Function type used as a parameter to ForEach member function. 



Public constructors 



Constructor 



Example 



TMListlmpO 

Constructs an empty list. 

TMListImp< MyObject, TStandardAllocator > list; // Create list to hold 
MyObjects 



list.Add(MyObject( 
list. Add (MyObject ( 
list. DetachAtHead! 



// Construct a MyObject, add to list 

// Add a second MyObject 

// Remove MyObject as head of list 



Public member functions 



Add 



Detach 



DetachAtHead 



FirstThat 



Flush 



ForEach 



IsEmpty 



int Add( const T& t ); 
Adds an object to the list. 

int Detach ( const T&); 

Removes the given object from the list. Returns for failure, 1 for success in 
removing the object. See TShouldDelete on page 408. 

int DetachAtHead ( ) ; 

Removes items from the head of a list without searching for a match. 

T *FirstThat( CondFunc cond, 'void *args ) const; 

Returns a pointer to the first object in the list that satisfies a given 
condition. You supply a test-function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 

See also: LastThat 

void Flush () ; 

Flushes the list without destroying it. 

void ForEach (IterFunc iter, void * args ); 

Executes function iter for list element. ForEach executes the given function 
iter for each element in the array. The args argument lets you pass arbitrary 
data to this function. 

int IsEmpty () const; 
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LastThat 



PeekHead 



Returns 1 if the list has no elements; otherwise returns 0. 

T *LastThat ( CondFunc cond, void *args) const; 

Returns a pointer to the last object in the list that satisfies a given condition. 
You supply a test function pointer cond that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the list meets the condition. 

See also: FirstThat, ForEach 

const T& PeekHead () const; 

Returns a reference to the Head item in the list, without removing it. 



Protected data members 



Head, Tail 



TMListElement<T,Alloc> Head, Tail; 

The elements before the first and after the last elements in the list. 



Protected member functions 



Find Detach 



FindPred 



virtual TMListElement<T,Alloc> *FindDetach( const T& t ) 

Determines whether an object is in the list, and returns a pointer to its 
predecessor. Returns if not found. 

virtual TMListElement<T,Alloc> *FindPred( const T& ); 

Finds the element that would be followed by the parameter. The function 
does not check whether the parameter is actually there. This can be used for 
inserting (insert after returned element pointer). 



TMListlteratorlmp template 



listimp.h 



template <class T, class Alloo class TMListlteratorlmp; 

Implements a list iterator that works on direct, managed list. For indirect 
list iteration see TMIListlteratorlmp on page 368. 



Public constructors 



Constructor TMListlteratorlmp (const TMListImp<T, Alloo &1) 

Constructs an iterator that traverses TMListlmp objects. 
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Public member functions 



Current 



Restart 



const T& Current ( ) 

Returns the current object. 

void Restart () 

Restarts iteration from the beginning of the list. 



Operators 



operator int operator int(); 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 

Operator ++ const T& operator ++ ( int ) 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

const T& operator ++ () 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 



TListlmp template 



listimp.h 



template <class T> class TListlmp; 

Implements a list of objects of type T. TListlmp assumes that T has 
meaningful copy semantics, and a default constructor. See TMListlmp on 
page 362 for members. 



TListlteratorlmp template 



listimp.h 



template <class T> class TListlteratorlmp; 

Implements a list iterator that works on direct, managed list. See 
TMListlteratorlmp on page 364 for members. 
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Public constructors 



Constructor TListIteratorImp( const TMListImp<T, TStandardAllocator> &1 ) 

Constructs an iterator that traverses TListlmp objects. 

TMSListlmp template listimp.h 

template <class T, class Alloo class TMSListlmp; 

Implements a managed, sorted list of objects of type T. TMSListlmp 
assumes that T has meaningful copy semantics, a meaningful < operator, 
and a default constructor. See TMListlmp on page 362 for members. 

TMSListlteratorlmp template listimp.h 

template <class T, class Alloo class TMSListlteratorlmp; 

Implements a list iterator that works on direct, managed, sorted list. See 
TMListlteratorlmp on page 364 for members. 

Public constructors 

Constructor TMSListlteratorlmp ( const TMSListImp<T, Alloo &1 ) 

Constructs an iterator that traverses TMSListlmp objects. 

TSListlmp template listimp.h 

template <class T> class TSListlmp; 

Implements a sorted list of objects of type T, using TStandardAllocator for 
memory management. TSListlmp assumes that T has meaningful copy 
semantics, a meaningful < operator, and a default constructor. See 
TMListlmp on page 362 for members. 

TSListlteratorlmp template listimp.h 

template <class T> class TSListlteratorlmp; 
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Implements a list iterator that works on direct, sorted list. See 
TMListlteratorlmp on page 364 for members. 



TMIListlmp template 



listimp.h 



template <class T, class Alloo class TMIListlmp; 

Implements a managed list of pointers to objects of type T. Because pointers 
always have meaningful copy semantics, this class can handle any type of 
object. 



CondFunc 



IterFunc 



Type definitions 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public member functions 



Add 



Detach 



FirstThat 



ForEach 



int Add( T *t ); 

Adds an object pointer to the list. 

int Detach ( T *t, int del = ) 

Removes the given object pointer from the list. The second argument 
specifies whether the object should be deleted. See TShouldDelete on 
page 408. 

T *FirstThat( CondFunc cond, void *args ) const; 

Returns a pointer to the first object in the list that satisfies a given 
condition. You supply a test-function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 

See also: LastThat 

void ForEach ( IterFunc iter, void *args ) 



Chapter 6, The C++ container classes 



367 



List containers 



LastThat 



PeekHead 



Executes function iter for each list element. ForEach executes the given 
function iter for each element in the array. The args argument lets you pass 
arbitrary data to this function. 

T *LastThat( CondFunc cond, void *args ) const; 

Returns a pointer to the last object in the list that satisfies a given condition. 
You supply a test function pointer cond that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the list meets the condition. 

See also: FirstThat, ForEach 

T * PeekHead () const; 

Returns the object pointer at the Head of the list, without removing it. 



Protected member functions 



FindPred 



virtual TMListElement<VoidPointer,Alloc> *FindPred( VoidPointer ); 

Finds the element that would be followed by the parameter. The function 
does not check whether the parameter is actually there. This can be used for 
inserting (insert after returned element pointer). 



TMIListlteratorlmp template 



listimp.h 



template <class T, class Alloo class TMIListlteratorlmp; 

Implements a list iterator that works with any managed indirect list. For 
direct lists, see TMListlteratorlmp on page 364. 



Public constructors 



Constructor 



TMIListlteratorlmp ( const TMIListImp<VoidPointer,Allocx &1 
Constructs an object that iterates on TMIListlmp objects. 



Public member functions 



Current 



Restart 



T *Current() 

Returns the current object pointer. 

void Restart () 
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Restarts iteration from the beginning of the list. 

Operators 



operator ++ T * operator ++ (int) 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

T * operator ++ () 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 

TIListlmp template listimp.h 

template <class T> class TIListlmp; 

Implements a list of pointers to objects of type T. Because pointers always 
have meaningful copy semantics, this class can handle any type of object. 
See TMIListlmp on page 367 for members. 

TIListlteratorlmp template listimp.h 

template. <class T> class TIListlteratorlmp; 

Implements a list iterator that works with any indirect list. See 
TMIListlteratorlmp on page 368 for members. 

Public constructors 

Constructor TIListlteratorlmp ( const TIListImp<T> &1 ) 

Constructs an object that iterates on TMIListlmp objects. 

TMISListlmp template listimp.h 

template <class T, class Alloo class TMISListlmp; 



Chapter 6, The C++ container classes 369 



List containers 



Find Detach 



FindPred 



Implements a managed sorted list of pointers to objects of type T. Because 
pointers always have meaningful copy semantics, this class can handle any 
type of object. 

Public member functions 

In addition to the member functions described here, TMISListlmp inherits 
other member functions from TMIListlmp (see page 367). 

virtual TMListElement<TVoidPointer,Alloc> *FindDetach(TVoidPointer) ; 

Determines whether an object is in the list, and returns a pointer to its 
predecessor. Returns if not found. 

virtual TMListElement<TVoidPointer,Alloc> *FindPred( TVoidPointer ); 

Finds the element that would be followed by the parameter. The function 
does not check whether the parameter is actually there. This can be used for 
inserting (insert after returned element pointer). 



TMISListlteratorlmp template 



listimp.h 



template <class T, class Alloo class TMISListlteratorlmp; 

Implements a list iterator that works with any managed indirect list. For 
direct lists, see TMListlteratorlmp on page 364. 



Public constructors 



Constructor 



TMISListlteratorlmp ( const TMISListImp<T, Alloo &1 ) : 
Constructs an object that iterates on TMISListlmp objects. 



TISListlmp template 



listimp.h 



template <class T> class TISListlmp; 

Implements a sorted list of pointers to objects of type T, using 
TStandardAllocator for memory management. Because pointers always have 
meaningful copy semantics, this class can handle any type of object. See 
TMISListlmp on page 369 for members. 
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TISListlteratorlmp template 



listimp.h 



template <class T> class TISListlteratorlmp; 

Implements a list iterator that works with any indirect list. See 
TMIListlteratorlmp on page 368 for members. 



Public constructors 



Constructor TISListlteratorlmp ( const TISListImp<T> &1 ) 

Constructs an object that iterates on TISListlmp objects. 



TMQueueAsVector template 



queues.h 



template <class T, class Alloo class TMQueueAsVector; 

Implements a managed queue of objects of type T, using a vector as the 
underlying implementation. TMQueueAsVector assumes T has meaningful 
copy semantics, a < operator, and a default constructor. The memory 
manager Alloc provides class-specific new and delete operators. 

Public constructors 

Constructor TMQueueAsVector ( unsigned sz = DEFAULT_QUEUE_SIZE ) 

Constructs a managed, vector-implemented queue, of sz size. 

Public member functions 



FirstThat 



Flush 



T *FirstThat(CondFunc, void *args ) const; 

Returns a pointer to the first object in the queue that satisfies a given 
condition. You supply a test-function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 

See also: LastThat 

void Flush () 

Flushes the queue without destroying it. The fate of any objects removed 
depends on the current ownership status. 
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See also: TShouldDelete::ownsElements 

ForEach vo i(j ForEach( IterFunc iter, void *args ); 

Executes function iter for each queue element. ForEach executes the given 
function iter for each element in the array. The args argument lets you pass 
arbitrary data to this function. 

Get T Get ( ) 

Removes the object from the head of the queue. If the queue is empty, it 
returns 0. Otherwise the removed object is returned. 

GetltemslnContainer i nt GetltemsInContainerO const; 

Returns the number of items in the queue. 
IsEmpty i n t isEmptyO const; 

Returns 1 if the queue has no elements; otherwise returns 0. 
IsFull i n t isFullO const; 

Returns 1 if the queue is full; otherwise returns 0. 

LastTnat t *LastThat( CondFunc cond, void *args ) const; 

Returns a pointer to the last object in the queue that satisfies a given 
condition. You supply a test function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the queue meets the condition. 

See also: FirstThat, ForEach 

Put void Put( T t ) 

Adds an object to (the tail of) a queue. 

TMQueueAsVectorlterator template queues.h 

template <class T, class Alloo class TMQueueAsVectorlterator; 

Implements an iterator object for managed, vector-based queues. See 
TMDequeAsVectorlterator on page 329 for members. 



Public constructors 



Constructor 



TMQueueAsVectorlterator ( const TMDequeAsVector<T, Alloo &q ) 
Constructs an object that iterates on TMQueueAsVector objects. 
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TQueueAsVector template 



queues.h 



Constructor 



template <class T> class TQueueAsVector; 

See TMQueueAsVector on page 371 for members. 

Public constructors 



TQueueAsVector ( unsigned sz = DEFAULT_QUEUE_SIZE ) 
Constructs a vector-implemented queue, of sz size. 



TQueueAsVectorlterator template 



queues.h 



template <class T> class TQueueAsVectorlterator; 

Implements an iterator object for vector-based queues. See 
TMDequeAsVectorlterator on page 329 for members. 



Constructor 



Public constructors 



TQueueAsVectorlterator ( const TQueueAsVector<T> &q ) 
Constructs an object that iterates on TQueueAsVector objects. 



TMIQueueAsVector template 



queues.h 



template <class T, class Alloo class TMIQueueAsVector; 

Implements a managed queue of pointers to objects of type T, using a 
vector as the underlying implementation. 



Constructor 



FirstThat 



Public constructors 

TMIQueueAsVector ( unsigned sz = DEFAULT_QUEUE_SIZE 
Constructs a managed, indirect queue, of sz size. 

Public member functions 

T *FirstThat( CondFunc, void *args ) const; 
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Returns a pointer to the first object in the queue that satisfies a given 
condition. You supply a test-function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 

See also: LastThat 

Flush vo id Flush ( TShouldDelete::DeleteType = TShouldDelete: :Def Delete ); 

Flushes the queue without destroying it. The fate of any objects removed 
depends on the current ownership status and the value of the dt argument. 

ForEach \roid. ForEach( IterFunc iter, void *args ); 

Executes function iter for each queue element. ForEach executes the given 
function iter for each element in the queue. The args argument lets you pass 
arbitrary data to this function. 

Get t *Get() 

Removes and returns the object pointer from the queue. If the queue is 
empty, it returns 0. 

GetltemslnContainer i nt GetltemsInContainerO const; 

Returns the number of items in the queue. 
IsEmpty int IsEmptyO const; 

Returns 1 if a queue has no elements; otherwise returns 0. 
IsFull i n t isFullO const; 

Returns 1 if a queue is full; otherwise returns 0. 

LastThat t *LastThat( CondFunc cond, void *args ) const; 

Returns a pointer to the last object in the queue that satisfies a given 
condition. You supply a test function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the queue meets the condition. 

See also: FirstThat, ForEach 

Put void Put( T *t ) 

Adds an object pointer to (the tail of) a queue. 

TMIQueueAsVectorlterator template queues.h 

template <class T, class Alloo class TMIQueueAsVectorlterator; 
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Implements an iterator object for managed, indirect, vector-based queues. 

Public constructors 

Constructor TMIQueueAsVectorIterator( const TMIDequeAsVector<T,Alloc> &q ) 

Constructs an object that iterates on TMIQueueAsVector objects. 

TIQueueAsVector template queues.h 

template <class T> class TIQueueAsVector; 

Implements a queue of pointers to objects of type T, using a vector as the 
underlying implementation. 

Public constructors 

Constructor TIQueueAsVector ( unsigned sz = DEFAULT_QUEUE_SIZE ) 

Constructs a indirect queue, of sz size. 

TIQueueAsVectorlterator template queues.h 

template <class T> class TIQueueAsVectorlterator; 

Implements an iterator object for indirect, vector-based queues. See 
TMDequeAsVectorlterator on page 329 for members. 



Public constructors 



Constructor 



TIQueueAsVectorlterator ( const TIQueueAsVector<T> &q ) 
Constructs an object that iterates on TIQueueAsVector objects. 



TMQueueAsDoubleList template queues.h 

template <class T, class Alloo class TMQueueAsDoubleList; 

Implements a managed queue of objects of type T, using a double-linked 
list as the underlying implementation. 
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Public member functions 



FirstThat 



Flush 



ForEach 



Get 



T *FirstThat( CondFunc cond, void *args ) const; 

Returns a pointer to the first object in the queue that satisfies a given 
condition. You supply a test-function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the queue meets the condition. 

See also: LastThat 

void Flush () 

Flushes objects from the queue. Flushes the queue without destroying it. 

void ForEach ( IterFunc iter, void *args ) 

Executes function iter for each queue element. ForEach executes the given 
function iter for each element in the array. The args argument lets you pass 
arbitrary data to this function. 

T Get!) 



Removes the object from the head of the queue. If the queue is empty, it 
throws the PRECONDITION exception in the debug version. In the non- 
debug version Get returns a meaningless object if the queue is empty. 

GetltemslnContainer i nt GetltemsInContainerO const; 

Returns the number of items in the queue. 

int IsEmptyO const; 

Returns 1 if a queue has no elements; otherwise returns 0. 

int IsFullO const; 

Returns 1 if a queue is full; otherwise returns 0. 

T * LastThat ( CondFunc cond, void *args ) const; 

Returns a pointer to the last object in the queue that satisfies a given 
condition. You supply a test function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 



IsEmpty 



IsFull 



LastThat 



Put 



See also: FirstThat, ForEach 

void Put( T t ) 

Adds an object to (the tail of) a queue. If the queue is full, it throws the 
PRECONDITION exception in the debug version. If the queue is full, the 
behavior of the non-debug version of Put is undefined. 
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TMQueueAsDoubleListlterator template queues.h 

template <class T, class Alloo class TMQueueAsDoubleListlterator; 

Implements an iterator object for list-based queues. See 
TMDequeAsDoubleListlterator on page 336 for members. 

Public constructors 

Constructor TMQueueAsDoubleListlterator ( const TMQueueAsDoubleList<T, Alloo & q ) 

Constructs an object that iterates on TMQueueAsDoubleList objects. 

TQueueAsDoubleList template queues.h 

template <class T> class TQueueAsDoubleList; 

Implements a queue of objects of type T, using a double-linked list as the 
underlying implementation. See TMQueueAsDoubleList on page 375 for 
members. 

TQueueAsDoubleListlterator template queues.h 

template <class T> class TQueueAsDoubleListlterator; 

Implements an iterator object for list-based queues. See 
TMDequeAsDoubleListlterator on page 336 for members. 

Public constructors 

Constructor TQueueAsDoubleListlterator ( const TQueueAsDoubleList<T> &q ) 

Constructs an object that iterates on TQueueAsDoubleList objects. 

TMIQueueAsDoubleList template queues.h 

template <class T, class Alloo class TMIQueueAsDoubleList; 

Implements a managed indirect queue of pointers to objects of type T, 
using a double-linked list as the underlying implementation. 
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Public member functions 



FirstThat 



Flush 



ForEach 



Get 



T *FirstThat( CondFunc cond, void *args ) const; 

Returns a pointer to the first object in the queue that satisfies a given 
condition. You supply a test-function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the queue meets the condition. 

See also: LastThat 

void Flush ( TShouldDelete::DeleteType dt = TShouldDelete: :Def Delete ) 

Flushes the queue without destroying it. The fate of any objects removed 
depends on the current ownership status and the value of the dt argument. 

void ForEach ( IterFunc iter, void *args ) 

Executes function iter for each queue element. ForEach executes the given 
function iter for each element in the queue. The args argument lets you pass 
arbitrary data to this function. 



T *Get() 

Removes and returns the object pointer from the queue. If the queue is 
empty, it throws the PRECONDITION exception in the debug version. In 
the non-debug version Get returns a meaningless object if the queue is 
empty. 

GetltemslnContainer i nt GetltemsInContainerO const; 

Returns the number of items in the queue. 

int IsEmptyO const; 

Returns 1 if the queue has no elements; otherwise returns 0. 

int IsFullO const; 

Returns 1 if the queue is full; otherwise returns 0. 

T *LastThat( CondFunc cond, void *args ) const; 

Returns a pointer to the last object in the dequeue that satisfies a given 
condition. You supply a test function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the queue meets the condition. 



IsEmpty 



IsFull 



LastThat 



Put 



See also: FirstThat, ForEach 

void Putt T *t ) 
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Adds an object pointer to (the tail of) a queue. If the queue is full, it throws 
the PRECONDITION exception in the debug version. If the queue is full, 
the behavior of the non-debug version of Put is undefined. 

TMIQueueAsDoubleListlterator template queues.h 

template <class T, class Alloo class TMIQueueAsDoubleListlterator; 

Implements an iterator object for indirect, list-based queues. See 
TMIDequeAsDoubleListlterator on page 338 for members. 

Public constructors 

Constructor TMIQueueAsDoubleListlterator! const TMIQueueAsDoubleList<T, Alloo & q ) 

Constructs an object that iterates on TMIQueueAsDoubleList objects. 

TIQueueAsDoubleList template queues.h 

Implements an indirect queue of pointers to objects of type T, using a 
double-linked list as the underlying implementation. See 
TMIQueueAsDoubleList on page 377 for members. 

TIQueueAsDoubleListlterator template queues.h 

Implements an iterator object for indirect, list-based queues. See 
TMIDequeAsDoubleListlterator on page 338 for members. 

Public constructors 

Constructor TIQueueAsDoubleListlterator ( const TIQueueAsDoubleList<T> & q ) 

Constructs an object that iterates on TIQueueAsDoubleList objects. 

TQueue template queues.h 

A simplified name for T Queue AsVector. 
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TQueuelterator template queues.h 

A simplified name for TQueueAsVectorlterator. 

TMSetAsVector template sets.h 

template <class T, class Alloo class TMSetAsVector; 

Implements a managed set of objects of type T, using a vector as the 
underlying implementation. A set, unlike a bag, cannot contain duplicate 
items. 

Public constructors 

Constructor TMSetAsVector ( unsigned sz = DEFAULT_SET_SIZE ) : 

Constructs an empty set. sz represents the number of items the set can hold. 

Public member functions 

In addition to the following member function, TMSetAsVector inherits 
member functions from TMBagAsVector. See TMBagAsVector on page 317 
for members. 

Add i n t Add( const T& t ); 

Adds an object to the set. 

TMSetAsVectorlterator template sets.h 

template <class T, class Alloo class TMSetAsVectorlterator; 

Implements an iterator object to traverse TMSetAsVector objects. See 
TMArrayAsVectorlterator on page 301 for members. 

Public constructors 

Constructor TMSetAsVectorlterator ( const TMSetAsVector<T, Alloo &s ) : 

Constructs an object that iterates on TMSetAsVector objects. 



380 Borland C++ for OS/2 Library Reference 



Set containers 



TSetAsVector template sets.h 

template <class T> class TSetAsVector; 

Implements a set of objects of type T, using a vector as the underlying 
implementation. T Standard Allocator is used to manage memory. See 
TMBagAsVector on page 317 for members. 

Public constructors 

Constructor TSetAsVector ( unsigned sz = DEFAULT_SET_SIZE ) : 

Constructs an empty set. sz represents the number of items the set can hold. 

TSetAsVectorlterator template sets.h 

template <class T> class TSetAsVectorlterator; 

Implements an iterator object to traverse TSetAsVector objects. See 
TMArrayAsVectorlterator on page 301 for members. 

Public constructors 

Constructor TSetAsVectorlterator ( const TSetAsVector<T> &s ) 

Constructs an object that iterates on TMSetAsVector objects. 

TMISetAsVector template sets.h 

template <class T, class Alloo class TMISetAsVector; 

Implements a managed set of pointers to objects of type T, using a vector as 
the underlying implementation. See TMIBagAsVector on page 319 for 
members. 

Public constructors 

Constructor TMISetAsVector ( unsigned sz = DEFAULT_SET_SIZE ) : 

Constructs an empty, managed, indirect set. sz represents the initial 
number of slots allocated. 
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Public member functions 



In addition to the following member function, TMISetAsVector inherits 
member functions from TMIBagAsVector. See TMIBagAsVector on page 319. 

Add int Add( T * ); 

Adds an object pointer to the set. 

TMISetAsVectorlterator template sets.h 

template <class T, class Alloo class TMISetAsVectorlterator; 

Implements an iterator object to traverse TMISetAsVector objects. See 
TMIArrayAsVectorlterator on page 306 for members. 

Public constructors 

Constructor TMISetAsVectorlterator ( const TMISetAsVector<T, Alloo &s ) 

Constructs an object that iterates on TMISetAsVector objects. 

TISetAsVector template sets.h 

template <class T> class TISetAsVector; 

Implements a set of pointers to objects of type T, using a vector as the 
underlying implementation. See TMIBagAsVector on page 319 for members. 

Public constructors 

Constructor TISetAsVector( unsigned sz = DEFAULT_SET_SIZE ) 

Constructs an empty, indirect bag. sz represents the initial number of slots 
allocated. 

TISetAsVectorlterator template sets.h 

template <class T> class TISetAsVectorlterator; 

Implements an iterator object to traverse TISetAsVector objects. See 

TMIArrayAsVectorlterator on page 306 for members. 
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Constructor 



TISetAsVectorIterator( const TISetAsVector<T> &s ) 
Constructs an object that iterates on TISetAsVector objects. 



TSet template 



sets.h 



A simplified name for TSetAsVector. 



TSetlterator template 



sets.h 



A simplified name for TSetAsVectorlterator. 



TMStackAsVector template 



stacks.h 



template <class T, class Alloo class TMStackAsVector; 

Implements a managed stack of objects of type T, using a vector as the 
underlying implementation. 



CondFunc 



IterFunc 



Type definitions 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public constructors 



Constructor • TMStackAsVector ( unsigned max = DEFAULT_STACK_SIZE ) 

Constructs a managed, vector-implemented stack, with max indicating the 
maximum stack size. 
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Public member functions 



Flush 



ForEach 



FirstThat t *FirstThat( CondFunc cond, void *args ) const; 

Returns a pointer to the first object in the stack that satisfies a given 
condition. You supply a test-function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via orgs. Returns if no 
object in the array meets the condition. 

See also: LastThat 

void Flush ( ) ; 

Flushes the stack without destroying it. 

See also: TShouldDeleter.ownsElements 

void ForEach ( IterFunc iter, void *args ) 

Executes function iter for each stack element. ForEach executes the given 
function iter for each element in the array. The args argument lets you pass 
arbitrary data to this function. 

GetltemslnContainer i nt GetltemsInContainerO const; 

Returns the number of items in the stack. 

int IsEmptyO const; 

Returns 1 if the stack has no elements; otherwise returns 0. 

int IsFullO const; 

Returns 1 if the stack is full; otherwise returns 0. 

T *LastThat( CondFunc cond, void *args ) const; 

Returns a pointer to the last object in the stack that satisfies a given 
condition. You supply a test function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 



IsEmpty 



IsFull 



LastThat 



Pop 



Push 



See also: FirstThat, ForEach 

T Pop() 

Removes the object from the top of the stack and returns the object. The fate 
of the popped object is determined by ownership. See TShouldDelete on 
page 408. 

void Push( const T& t ) 

Pushes an object on the top of the stack. 
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Top _ const T& Top() const; 

Returns but does not remove the object at the top of the stack. 

TMStackAsVectorlterator template stacks.h 

template <class T, class Alloo class TMStackAsVectorlterator; 

Implements an iterator object for managed, vector-based stacks. See 
TMVectorlteratorlmp on page 393 for members. 

Public constructors 

Constructor TMStackAsVectorlterator ( const TMStackAsVector<T, Alloo & s ) : 

Constructs an object that iterates on TMStackAsVector objects. 

TStackAsVector template stacks.h 

template <class T> class TStackAsVector; 

Implements a stack of objects of type T, using a vector as the underlying 
implementation, and T Standard Allocator for memory management. 



Public constructors 



Constructor 



TStackAsVector ( unsigned max = DEFAULT_STACK_SIZE ) 

Constructs a vector-implemented stack, with max indicating the maximum 
stack size. 



TStackAsVectorlterator template stacks.h 

template <class T> class TStackAsVectorlterator; 

Implements an iterator object for managed, vector-based stacks. See 
TMVectorlteratorlmp on page 393 for members. 
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Public constructors 



Constructor TStackAsVectorIterator( const TStackAsVector<T> & s ) : 

Constructs an object that iterates on TStackAsVector objects. 



TMIStackAsVector template 



stacks.h 



template <class T, class Alloo class TMIStackAsVector; 

TMIStackAsVector implements a managed stack of pointers to objects of 
type T, using a vector as the underlying implementation. 



CondFunc 



IterFunc 



Type definitions 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public constructors 



Constructor 



TMIStackAsVector ( unsigned max = DEFAULT_STACK_SIZE ) 

Constructs a managed, indirect, vector-implemented stack, with max 

indicating the maximum stack size. 



Public member functions 



FirstThat 



Flush 



T *FirstThat( CondFunc cond, void *args ) const; 

Returns a pointer to the first object in the stack that satisfies a given 
condition. You supply a test-function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via orgs. Returns if no 
object in the array meets the condition. 

See also: LastThat 

void Flush( TShouldDelete::DeleteType = TShouldDelete: :Def Delete ) 
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ForEach 



Flushes the stack without destroying it. The fate of any objects removed 
depends on the current ownership status and the value of the dt argument. 

See also: TShouldDeleter.ownsElements 

void ForEach ( IterFunc iter, void *args ) 



IsEmpty 



IsFull 



LastThat 



Executes function iter for each stack element. ForEach executes the given 
function iter for each element in the array. The args argument lets you pass 
arbitrary data to this function. 

GetltemslnContainer i nt GetltemsInContainerO const; 

Returns the number of items in the stack. 

int IsEmpty () const; 

Returns 1 if the stack has no elements; otherwise returns 0. 

int IsFull () const; 

Returns 1 if the stack is full; otherwise returns 0. 

T *LastThat( CondFunc cond, void *args ) const; 

Returns a pointer to the last object in the stack that satisfies a given 
condition. You supply a test function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 

See also: FirstThat, ForEach 

T *Pop() 

Removes the object from the top of the stack and returns a pointer to the 
object. The fate of the popped object is determined by ownership. See 
TShouldDelete on page 408. 

void Push( T *t ) 

Pushes a pointer to an object on the top of the stack. 

T *Top() const; 

Returns but does not remove the object pointer at the top of the stack. 



Pop 



Push 



Top 



TMIStackAsVectorlterator template 



stacks.h 



template <class T, class Alloo class TMIStackAsVectorlterator; 

Implements an iterator object for managed, indirect, vector-based stacks. 
See TMVectorlteratorlmp on page 393 for members. 
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Public constructors 



Constructor TMIStackAsVectorIterator( const TMIStackAsVector<T,Alloc> & s ) 

Constructs an object that iterates on TMIStackAsVector objects. 

TIStackAsVector template stacks.h 

template <class T> class TIStackAsVector; 

Implements an indirect stack of pointers to objects of type T, using a vector 
as the underlying implementation. See TMIStackAsVector on page 386 for 
members. 

Public constructors 

Constructor TIStackAsVector ( unsigned max = DEFAULT_STACK_SIZE ); 

Constructs an indirect, vector-implemented stack, with max indicating the 
maximum stack size. 

TIStackAsVectorlterator template stacks.h 

template <class T> class TIStackAsVectorlterator; 

Implements an iterator object for indirect, vector-based stacks. See 
TMIVectorlteratorlmp on page 402 for members. 

Public constructors 

Constructor TMIStackAsVectorIterator( const TMIStackAsVector<T,Alloc> & s ) 

Constructs an object that iterates on TIStackAsVector objects. 

TMStackAsList template stacks.h 

template <class T, class Alloo class TMStackAsList; 

Implements a managed stack of objects of type T, using a list as the 
underlying implementation. See TMStackAsVector on page 383 for 
members. 
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TMStackAsListlterator template stacks.h 

template <class T, class Alloo class TMStackAsListlterator; 

Implements an iterator object for managed, list-based stacks. See 
TMListlteratorlmp on page 364 for members. 

Public constructors 

Constructor TMStackAsListlterator! const TMStackAsList<T, Alloo is): 

TMListIteratorImp<T, Alloo (s. Data) 

Constructs an object that iterates on TMStackAsList objects. 

TStackAsList template stacks.h 

template <class T> class TStackAsList; 

Implements a managed stack of objects of type T, using a list as the 
underlying implementation. See TMStackAsVector on page 383 for 
members. 

TStackAsListlterator template stacks.h 

template <class T> class TStackAsListlterator; 

Implements an iterator object for list-based stacks. See TMVectorlteratorlmp 
on page 393 for members. 

Public constructors 

Constructor TStackAsListlterator ( const TStackAsList<T> & s ); 

Constructs an object that iterates on TIStackAsVector objects. 

TMIStackAsList template stacks.h 

template <class T, class Alloo class TMIStackAsList; 
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Implements a managed stack of pointers to objects of type T, using a linked 
list as the underlying implementation. See TMIStackAsVector on page 386 
for members. 

TMIStackAsListlterator template stacks.h 

template <class T, class Alloo class TMIStackAsListlterator; 

Implements an iterator object for managed, indirect, list-based stacks. See 
TMIListlteratorlmp on page 368 for members. 

Public constructors 

Constructor TMIStackAsListlterator ( const TMIStackAsList<T, Alloo & s ) 

Constructs an object that iterates on TMIStackAsList objects. 

TIStackAsList template stacks.h 

template <class T> class TIStackAsList; 

Implements TMIStackAsList with the standard allocator T Standard Allocator. 
See TMIStackAsVector on page 386 for members. 

TIStackAsListlterator template stacks.h 

template <class T> class TIStackAsListlterator; 

Implements an iterator object for indirect, list-based stacks. See 
TMIVectorlteratorlmp on page 402 for members. 

Public constructors 

Constructor TIStackAsListlterator ( const TIStackAsList<T> & s ) 

Constructs an object that iterates on TIStackAsList objects. 

TStack template stacks.h 

A simplified name for TStackAsVector. 
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TStacklterator template 



stacks.h 



A simplified name for TStackAsVectorlterator. 



TMVectorlmp template 



vectimp.h 



template <class T, class Alloo class TMVectorlmp; 

Implements a managed vector of objects of type T. TMVectorlmp assumes 
that T has meaningful copy semantics, and a default constructor. 



CondFunc 



IterFunc 



Type definitions 



typedef int ( *CondFunc) (const T & # void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public constructors 



Constructor 



Constructor 



Constructor 



TMVectorlmp ( ) ; 

Constructs a vector with no entries. 

TMVectorImp( unsigned sz, unsigned = ); 

Constructs a vector of sz objects, initialized by default to 0. 

TMVectorImp( const TMVectorImp<T, Alloo & ); 
Constructs a vector copy. 



Public member functions 



FirstThat 



T *FirstThat( CondFunc cond, void *args ) const; 

Returns a pointer to the first object in the vector that satisfies a given 
condition. You supply a test-function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the vector meets the condition. 
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Flush 



ForEach 



GetDelta 



LastThat 



Limit 



Resize 



T *FirstThat( CondFunc cond, void *args, unsigned start, 
unsigned stop) const; 

This version of FirstThat allows you to specify a range to be searched. 
Returns a pointer to the first object in the vector that satisfies a given 
condition. You supply a test-function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the vector meets the condition. 

See also: LastThat 

void Flush( unsigned stop = UINT_MAX, unsigned start = ); 

Flushes the vector without destroying it. The fate of any objects removed 
depends on the current ownership status and the value of the first 
argument. 

See also: TShouldDelete::ownsElements 

void ForEach ( IterFunc iter, void *args ) 

Returns a pointer to the first object in the vector that satisfies a given 
condition. ForEach executes the given function iter for each element in the 
array. The args argument lets you pass arbitrary data to this function. 

void ForEach ( IterFunc iter, void *, unsigned start, unsigned stop); 

This version allows you to specify a range. 

See also: LastThat 

virtual unsigned GetDelta ( ) const; 

Returns the growth delta for the array. 

T *LastThat( CondFunc cond, void *args ) const; 

Returns a pointer to the last object in the vector that satisfies a given 
condition. You supply a test function pointer cond that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the vector meets the condition. 

T *LastThat( CondFunc cond, void *args, unsigned start, 
unsigned stop ) const; 

This version allows you to specify a range. 

See also: FirstThat, ForEach 

unsigned Limit () const; 

Returns the number of items that the vector can hold. 

void Resize ( unsigned sz, unsigned offset = ); 
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Top 



Creates a new vector of size sz. The existing vector is copied to the 
expanded vector, then deleted. In a vector of pointers the entries are 
zeroed. In an array of objects the default constructor is invoked for each 
unused element, offset is the location in the new vector where the first 
element of the old vector should be copied. This is needed when the vector 
has to be extended downward. 

virtual unsigned Top() const; 

Returns the index of the current top element. For plain vectors Top returns 
Lim; for counted and sorted vectors Top returns the current insertion point. 



operator [ ] 
operator = 



Operators 



T & operator [] ( unsigned index ) const; 

Returns a reference to the object at index. 

const TMVectorlmp<T,Alloc> & operator = ( const TMVectorImp<T,Alloc> & 

Provides the vector assignment operator. 



Protected data members 



Lim 



unsigned Lim; 

Lim stores the upper limit for indexes into the vector. 



Protected member functions 



Zero 



virtual void Zero( unsigned, unsigned ) 

Provides for zeroing vector contents within the specified range. 



TMVectorlteratorlmp template 



vectimp.h 



template <class T, class Alloo class TMVectorlteratorlmp; 

Implements a vector iterator that works with any direct, managed vector of 
objects of type T. For indirect vector iterators, see TMIVectorlteratorlmp on 
page 402. 
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Public constructors 



Constructor 



Constructor 



TMVectorlteratorlmpf const TMVectorImp<T,Alloc> &v ) 

Creates an iterator object to traverse TMVectorlmp objects. 

TMVectorIteratorImp( const TMVectorImp<T,Alloc> &v, unsigned start, 
unsigned stop ) 

Creates an iterator object to traverse TMVectorlmp objects. A range can be 
specified. 



Public member functions 



Current 



Restart 



const T& Current () ; 

Returns the current object. 

void Restart () ; 

Restarts iteration over the whole vector. 

void Restart ( unsigned start, unsigned stop 

Restarts iteration over the given range. 



Operators 



operator ++ cons t t& operator ++(int); 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

const T& operator ++ ( ) ; 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 

Operator int operator int(); 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 



TVectorlmp template 



vectimp.h 



template <class T> class TVectorlmp; 
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Implements a vector of objects of type T. TVectorlmp assumes that T has 
meaningful copy semantics, and a default constructor. See TMVectorlmp on 
page 391 for members. 

Public constructors 



Constructor 



Constructor 



Constructor 



TVectorlmp ( ) 

Constructs a vector with no entries. 

TVectorlmp ( unsigned sz, unsigned = ) 

Constructs a vector of sz objects, initialized by default to 0. 

TVectorlmp ( const TVectorImp<T> &v ) 
Constructs a vector copy. 



TVectorlteratorlmp template 



vectimp.h 



Constructor 



Constructor 



template <class T> class TVectorlteratorlmp; 

Implements a vector iterator that works with any direct vector of objects of 
type T. See TMVectorlteratorlmp on page 393 for members. 

Public constructors 

TVectorlteratorlmp ( const TVectorImp<T> &v ) 

Creates an iterator object to traverse TVectorlmp objects. 

TVectorlteratorlmp ( const TVectorImp<T> &v, unsigned start, unsigned stop 

Creates an iterator object to traverse TVectorlmp objects. A range can be 
specified. 



TMCVectorlmp template 



vectimp.h 



template <class T, class Alloo class TMCVectorlmp; 

Implements a managed, counted vector of objects of type T. TMCVectorlmp 
assumes that T has meaningful copy semantics, and a default constructor. 
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Public constructors 



Constructor 



Constructor 



TMCVectorlmp ( ) ; 

Constructs a vector with no entries. 

TMCVectorlmp ( unsigned sz, unsigned = ); 

Constructs a vector of sz objects, initialized by default to 0. 



Public member functions 



Add 



AddAt 



Count 



Detach 



Find 



GetDelta 



In addition to the member functions described here, TMCVectorlmp inherits 
member functions from TMVectorlmp (see page 391). 

int Add( const T& t ) ; 

Adds an object to the vector and increments Count _. 

int AddAt ( const T&, unsigned ); 

Adds an object to the vector at the specified location, and increments 
Count _. 

unsigned Count ( ) const; 

Returns Count_. 

int Detach ( unsigned loc ); 
int Detach ( const T& loc ); 

Remove by specifying the object or its index. 

virtual unsigned Find( const T& ) const; 

Finds the specified object and returns the object's index; otherwise returns 
INT_MAX. 

virtual unsigned GetDelta ( ) const; 

Returns Delta. 



Protected data members 



Count 



In addition to the data members described here, TMCVectorlmp inherits 
data members from TMVectorlmp (see page 391). 

unsigned Counts- 
Maintains the number of objects in the vector. 
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Delta 



Top 



unsigned Delta; 

Specifies the size increment to be used when the vector grows. 

virtual unsigned Top( ) const; 
Returns Count . 



TMCVectorlteratorlmp template 



vectimp.h 



template <class T, class Alloo class TMCVectorlteratorlmp; 

Implements a vector iterator that works with any direct, managed, counted 
vector of objects of type T. See TMVectorlteratorlmp on page 393 for 
members. 

Public constructors 

Constructor TMCVectorlteratorlmp ( const TMCVectorImp<T, Alloo &v ) 

Creates an iterator object to traverse TMCVectorlmp objects. 

Constructor TMVectorIteratorImp( const TMCVectorImp<T, Alloo &v, unsigned start, 

unsigned stop ) 

Creates an iterator object to traverse TMCVectorlmp objects. A range can be 
specified. 



TCVectorlmp template 



vectimp.h 



template <class T> class TCVectorlmp; 

Implements a counted vector of objects of type T. TCVectorlmp assumes that 
T has meaningful copy semantics, and a default constructor. See 
TMCVectorlmp on page 395 for members. 

Public constructors 



Constructor 



Constructor 



TCVectorlmp ( ) ; 

Constructs a vector with no entries. 

MCVectorlmp ( unsigned sz, unsigned = 
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Constructs a vector of sz objects, initialized by default to 0. 



TCVectorlteratorlmp template 



vectimp.h 



template <class T> class TCVectorlteratorlmp; 

Implements a vector iterator that works with any direct, counted vector of 
objects of type T. See TMCVectorlteratorlmp on page 397 for members. 

Public constructors 

Constructor TCVectorlteratorlmp ( const TCVectorImp<T> &v ) 

Creates an iterator object to traverse TCVectorlmp objects. 

Constructor TCVectorlteratorlmp! const TCVectorImp<T> &v, unsigned start, 

unsigned stop ) 

Creates an iterator object to traverse TCVectorlmp objects. A range can be 
specified. 



TMSVectorlmp template 



vectimp.h 



template <class T, class Alloo class TMSVectorlmp; 

Implements a managed, sorted vector of objects of type T. TMSVectorlmp 
assumes that T has meaningful copy semantics, a meaningful < operator, 
and a default constructor. See TMCVectorlmp on page 395 for members. 



Public constructors 



Constructor 



Constructor 



TMSVectorlmp () 

Constructs a vector with no entries. 
, TMSVectorlmp ( unsigned sz, unsigned d = ) 
Constructs a vector of sz objects, initialized by default to 0. 



TMSVectorlteratorlmp template 



vectimp.h 



template <class T, class Alloo class TMSVectorlteratorlmp; 
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Implements a vector iterator that works with any direct, managed, sorted 
vector of objects of type T. See TMVectorlteratorlmp on page 393 for 
members. 



Public constructors 



Constructor 



Constructor 



TMSVectorIteratorImp( const TMSVectorImp<T,Alloc> &v ) 

Creates an iterator object to traverse TMSVectorlmp objects. 

TMSVectorIteratorImp( const TMSVectorImp<T,Alloc> &v, unsigned start, 
unsigned stop ) 

Creates an iterator object to traverse TMSVectorlmp objects. A range can be 
specified. 



TSVectorlmp template 



vectimp.h 



template <class T> class TSVectorlmp; 

Implements a sorted vector of objects of type T. TSVectorlmp assumes that T 
has meaningful copy semantics, a meaningful < operator, and a default 
constructor. See TMCVectorlmp on page 395 for members. 

Public constructors 



Constructor 



Constructor 



TSVectorlmp ( ) 

Constructs a vector with no entries. 

TSVectorlmp ( unsigned sz, unsigned d = ) 

Constructs a vector of sz objects, initialized by default to 0. 



TSVectorlteratorlmp template 



vectimp.h 



template <class T> class TSVectorlteratorlmp; 

Implements a vector iterator that works with any direct, sorted vector of 
objects of type T. See TMVectorlteratorlmp on page 393 for members. 
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Public constructors 



Constructor 



Constructor 



TSVectorIteratorImp( const TSVectorImp<T> &v ) 

Creates an iterator object to traverse TSVectorlmp objects. 

TSVectorIteratorImp( const TSVectorImp<T> &v, unsigned start, 
unsigned stop ) 

Creates an iterator object to traverse TSVectorlmp objects. A range can be 
specified. 



TMIVectorlmp template 



vectimp.h 



template <class T, class Alloo class TMIVectorlmp; 

Implements a managed vector of pointers to objects of type T. Because 
pointers always have meaningful copy semantics, this class can handle any 
type of object. 



CondFunc 



IterFunc 



Type definitions 

typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public constructors 



Constructor TMIVectorlmp ( unsigned sz ); 

Constructs a managed vector of pointers to objects, sz represents the vector 
size. 



Public member functions 



FirstThat 



T *FirstThat( CondFunc cond, void *args ) const; 

Returns a pointer to the first object in the vector that satisfies a given 
condition. You supply a test-function pointer cond that returns true for a 
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Flush 



ForEach 



GetDelta 



LastThat 



Limit 



Resize 



Top 



certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. 

T *FirstThat( CondFunc cond, void *args, unsigned, unsigned ) const; 

This version allows specifying a range to be searched. You supply a test- 
function pointer cond that returns true for a certain condition. You can pass 
arbitrary arguments via args. Returns if no object in the array meets the 
condition. 

void Flush( unsigned = 0, unsigned stop = UINT_MAX, unsigned start = ); 

Flushes the vector without destroying it. The fate of any objects removed 
depends on the current ownership status and the value of the first 
argument. A range to be flushed can be specified with the last two 
arguments. 

void ForEach ( IterFunc iter, void *args ) 

Returns a pointer to the first object in the vector that satisfies a given 
condition. See TMArrayAsVector::FirstThat. 

void ForEach ( IterFunc iter, void *, unsigned, unsigned ); 

This version allows specifying a range. 

virtual unsigned GetDelta ( ) const; 

Returns the growth delta for the array. 

T *LastThat( CondFunc cond, void *args ) const; 

Returns a pointer to the last object in the vector that satisfies a given 
condition. See TMArrayAsVector::LastThat. 

T *LastThat( CondFunc cond, void *args, unsigned, unsigned ) const; 

This version allows specifying a range. 

unsigned Limit () const; 

Returns the number of items that the vector can hold. 

void Resize( unsigned sz, unsigned offset = ) ; 

Creates a new vector of size sz. The existing vector is copied to the 
expanded vector, then deleted. In a vector of pointers the entries are 
zeroed. In an array of objects the default constructor is invoked for each 
unused element, offset is the location in the new vector where the first 
element of the old vector should be copied. This is needed when the vector 
has to be extended downward. 

virtual unsigned Top() const; 
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Zero 



operator [ ] 



Returns the index of the current top element. For plain vectors Top returns 
Lim; for counted and sorted vectors Top returns the current insertion point. 

virtual void Zero( unsigned, unsigned ); 

Provides for zeroing vector contents within the specified range. 

Operators 

T * & operator [] ( unsigned index ) 

T * & operator [] ( unsigned index ) const; 

Returns a reference to the object at index. 



TMIVectorlteratorlmp template 



vectimp.h 



template <class T, class Alloo class TMIVectorlteratorlmp; 
Implements a vector iterator that works with an indirect, managed vector. 



Constructor 



Constructor 



Public constructors 



TMIVectorlteratorlmp ( const TMIVectorImp<T, Alloo &v ) 
Creates an iterator object to traverse TMIVectorlmp objects. 

TMIVectorlteratorlmp ( const TMIVectorImp<T, Alloo &v, unsigned 1, unsigned u 

Creates an iterator object to traverse TMIVectorlmp objects. A range can be 
specified. 



Public member functions 



Current 



Restart 



T *Current ( ) ; 

Returns a pointer to the current object. 

void Restart () ; 

Restarts iteration over the whole vector. 

void Restart ( unsigned start, unsigned stop 
Restarts iteration over the given range. 
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Operators 



operator ++ const t& operator ++(int); 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

const T& operator ++ ( ) ; 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 

operator int operator int ( ) ; 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 

TlVectorlmp template vectimp.h 

template <class T> class TlVectorlmp; 

Implements a vector of pointers to objects of type T. Because pointers 
always have meaningful copy semantics, this class can handle any type of 
object. See TMIVectorlmp on page 400 for members. 



Public constructors 



Constructor 



TlVectorlmp ( unsigned sz, unsigned d = ) 

Constructs an indirect vector of sz size, with default initialization of 0. 



TlVectorlteratorlmp template vectimp.h 

template <class T> class TlVectorlteratorlmp; 

Implements a vector iterator that works with an indirect, managed vector. 
See TMIVectorlteratorlmp on page 402 for members. 

Public constructors 

Constructor TlVectorlteratorlmp ( const TIVectorImp<T> &v ) 

Creates an iterator object to traverse TlVectorlmp objects. 
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Constructor TIVectorIteratorImp( const TIVectorImp<T> &v, unsigned 1, unsigned u ) 

Creates an iterator object to traverse TlVectorlmp objects. A range can be 
specified. 

TMICVectorlmp template vectimp.h 

template <class T, class Alloo class TMICVectorlmp; 

Implements a managed, counted vector of pointers to objects of type T. 
Because pointers always have meaningful copy semantics, this class can 
handle any type of object. 

Public constructors 

Constructor TMICVectorlmp (unsigned sz, unsigned d = ) 

Constructs a managed, counted vector of pointers to objects, sz represents 
the vector size, d represents the initialization value. 

Public member functions 

In addition to the following member functions, TMICVectorlmp inherits 
other member functions and operators from TMIVectorlmp (see page 400). 

Add i n t Add( T *t ); 

Adds an object to the vector. 
Find unsigned Find( T *t ) const; 

Finds the specified object pointer, and returns its index. 

Protected member functions 

rind virtual unsigned Find( void * ) const; 

Finds the specified pointer and returns its index. 

TMICVectorlteratorlmp template vectimp.h 

template <class T, class Alloo class TMICVectorlteratorlmp; 
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Implements a vector iterator that works with an indirect, managed, 
counted vector. See TMIVectorlteratorlmp on page 402 and 
TMVectorlteratorlmp on page 393 for members. 

Public constructors 

Constructor TMICVectorIteratorImp( const TMICVectorImp<T,Alloc> &v ) 

Creates an iterator object to traverse TMCIVectorlmp objects. 

Constructor TMICVectorIteratorImp( const TMICVectorImp<T,Alloc> &v, unsigned 1, 

unsigned u ) 

Creates an iterator object to traverse TMICVectorlmp objects. A range can be 
specified. 

TlCVectorlmp template vectimp.h 

template <class T> class TlCVectorlmp; 

Implements a counted vector of pointers to objects of type T. Because 
pointers always have meaningful copy semantics, this class can handle any 
type of object. See TMICVectorlmp on page 404 for members. 

Public constructors 

Constructor TICVectorImp( unsigned sz, unsigned d = ) 

Constructs a counted vector of pointers to objects, sz represents the vector 
size, d represents the initialization value. 

TlCVectorlteratorlmp template vectimp.h 

template <class T> class TlCVectorlteratorlmp; 

Implements a vector iterator that works with an indirect, managed, 
counted vector. See TMIVectorlteratorlmp on page 402 and 
TMVectorlteratorlmp on page 393 for members. 
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Public constructors 



Constructor 



Constructor 



TICVectorIteratorImp( const TICVectorImp<T> &v ) 
Creates an iterator object to traverse TICVectorImp objects. 

TICVectorlteratorlmpt const TICVectorImp<T> &v, unsigned 1, unsigned u ) 

Creates an iterator object to traverse TICVectorImp objects. A range can be 
specified. 



TMISVectorlmp template 



vectimp.h 



template <class T, class Alloo class TMISVectorlmp; 

Implements a managed, sorted vector of pointers to objects of type T. 
Because pointers always have meaningful copy semantics, this class can 
handle any type of object. See TMICVectorlmp on page 404 for members. 

Public constructors 

Constructor TMISVectorImp( unsigned sz, unsigned d = ); 

Constructs a managed, sorted vector of pointers to objects, sz represents the 
vector size, d represents the initialization value. 



TMISVectorlteratorlmp template 



vectimp.h 



template <class T, class Alloo class TMISVectorlteratorlmp; 

Implements a vector iterator that works with an indirect, managed, sorted 
vector. See TMIVectorlteratorlmp on page 402 and TMVectorlteratorlmp on 
page 393 for members. 



Public constructors 



Constructor 



Constructor 



TMISVectorlteratorlmp ( const TMISVectorImp<T, Alloo &v ) 

Creates an iterator object to traverse TMIVectorlmp objects. 

TMISVectorlteratorlmp ( const TMISVectorImp<T, Alloo &v, unsigned 1, 
unsigned u ) 
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Creates an iterator object to traverse TMIVectorlmp objects. A range can be 
specified. 



TlSVectorlmp template 



vectimp.h 



template <class T> class TlSVectorlmp; 

Implements a sorted vector of pointers to objects of type T. Because 
pointers always have meaningful copy semantics, this class can handle any 
type of object. See TMICVectorlmp on page 404 for members. 

Public constructors 

Constructor TISVectorImp( unsigned sz, unsigned d = ) 

Constructs a managed, sorted vector of pointers to objects, sz represents the 
vector size, d represents the initialization value. 



TlSVectorlteratorlmp template 



vectimp.h 



Constructor 



Constructor 



template <class T> class TlSVectorlteratorlmp; 

Implements a vector iterator that works with an indirect, managed, sorted 
vector. See TMIVectorlteratorlmp on page 402 and TMVectorlteratorlmp on 
page 393 for members. 

Public constructors 

TlSVectorlteratorlmp ( const TISVectorImp<T> &v ) 
Creates an iterator object to traverse TlSVectorlmp objects. 

TlSVectorlteratorlmp! const TISVectorImp<T> &v, unsigned 1, unsigned u ) 

Creates an iterator object to traverse TlSVectorlmp objects. A range can be 
specified. 
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TShouldDelete class 



shddel.h 



class TShouldDelete; 

TShouldDelete maintains the ownership state of an indirect container. The 
fate of objects that are removed from a container can be made to depend on 
whether the container owns its elements or not. Similarly, when a container 
is destroyed, ownership can dictate the fate of contained objects that are 
still in scope. As a virtual base class, TShouldDelete provides ownership 
control for all containers classes. The member function OwnsElements can 
be used either to report or to change the ownership status of a container. 
The member function DelObj is used to determine if objects in containers 
should be deleted or not. 

Public data members 

enum DeleteType { NoDelete, Def Delete, Delete }; 

Enumerates values to determine whether or not an object should be deleted 
upon removal from a container. 

Public constructors 



Constructor 



TShouldDelete ( DeleteType dt = Delete ) 

Creates a TShouldDelete object. See member function DelObj. 



Public member functions 



OwnsElements i n t OwnsElements ( ) 

Returns 1 if the container owns its elements; otherwise returns 0. 

void OwnsElements ( int del ) 

Changes the ownership status as follows: if del is 0, ownership is turned off; 
otherwise ownership is turned on. 



Protected member functions 



DelObj 



int DelObj ( DeleteType dt ) 

Tests the state of ownership and returns 1 if the contained objects should be 
deleted or if the contained elements should not be deleted. The factors 
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determining this are the current ownership state, and the value of dt, as 
shown in the following table. 

delObj 
ownsElements No Yes 

NoDelete No No 

DefDelete No Yes 

Delete Yes Yes 

delObj returns 1 if (dt is Delete) or (dt is DefDelete and the container currently 
owns its elements). Thus a dt of NoDelete returns (don't delete) regardless 
of ownership; a dt of Delete return 1 (do delete) regardless of ownership; 
and a dt of DefDelete returns 1 (do delete) if the elements are owned, but a 
(don't delete) if the objects are not owned. 
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The C++ mathematical classes 



This chapter describes Borland C++ mathematics based on C++ classes. 
These mathematical operations are available only in C++ programs. How- 
ever, a C++ program that uses any of these classes, the numerical types that 
the classes define, or any of the classes' friend and member functions can 
use any of ANSI C Standard mathematics routines. 

There are two classes, bed and complex, that construct numerical types. 
Along with these numerical types, each class defines the functions with 
which to carry out operations with their respective types (for example, 
converting to and from the bed and complex type). Each class also overloads 
all necessary operators. 

The mathematical classes are independent of any hierarchy. However, each 
class includes the iostream.h header file. 

The portability for bed and complex is as follows: 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




" 


■ 






■ 



bed 



bcd.h 



The class constructors create binary coded decimals (BCD) from integers or 
floating-point numerical types. The friend function real, described on page 
413, converts bed numbers to long double. 

Once you construct bed numbers, you can freely mix them in expressions 
with ints, doubles, and other numeric types. You can also use bed numbers 
in any of the ANSI C Standard mathematical functions. 

The following ANSI C math functions are overloaded to operate with bed 
types: 

friend bed absfbed &); 
friend bed acos(bcd &) ; 
friend bed asin(bcd &); 
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bed 



Constructor 



Constructor 



friend bed atan(bcd &); 

friend bed cos (bed &); 

friend bed cosh (bed &) ; 

friend bed exp(bcd &) ; 

friend bed log (bed &) ; 

friend bed loglO(bcd &); 

friend bed pow(bcd & base, bed & expon) ; 

friend bed sin (bed &); 

friend bed sinh(bcd &) ; 

friend bed sqrt(bcd &) ; 

friend bed tan (bed &) ; 

friend bed tanh(bcd &); 

See the documentation of these functions in Chapter 2. 

The bed class also overloads the operators +, -, *, /, +=, -=, *=, /=, =, ==, and 
!=. These operators provide bed arithmetic manipulation in the usual sense. 

The operators « and » are overloaded for stream input and output of bed 
numbers, as they are for other data types in iostream.h. 

bed numbers have about 17 decimal digits precision, and a range of about 
1 x 10" 125 to 1 x 10 125 . 

The number is rounded according to the rules of banker's rounding, which 
means round to nearest whole number, with ties being rounded to an even 
digit. 

Public constructors 

bcd(); 

The default constructor. You typically use this to declare a variable of type 
bed. 

bed i; // Construct a bed-type number. 

bed j = 37; // Construct and initialize a bed-type number. 

bcd(int x) ; 

This constructor defines a bed variable from an int variable or directly from 
an integer. 

int i = 15; 

bed j = bcd(i).; // Initialize j with a previously declared type. 

bed k = bcd(12); // Construct k from the integer provided. 

The above example provides these variables: 

■ i = 15 j = 15 k = 12 
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bed 



Constructor 



Constructor 



Constructor 



Constructor 



Constructor 



bed (unsigned int x) ; 

This constructor defines a bed variable from a variable that was previously 
declared to be an unsigned int type. An unsigned integer can be provided 
directly to the constructor. 

bed (long x) ; 

This constructor defines a bed variable from an long variable or directly 
from a long value. 

bed (unsigned long x) ; 

This constructor defines a bed variable from a variable that was previously 
declared to be an unsigned long type. 

bed (double x, int decimals - Max); 

This constructor defines a bed variable from a variable that was previously 
declared to be a floating point double type. The constructor also creates a 
variable directly from a double value. 

To specify a precision level (that is, the number of digits after the decimal 
point) that is different from the default, use the variable decimals; for 
example, 

double x = 1.2345; // Declare and initialize in the usual manner. 
bed y = bcd(x, 2); // Create a bed numerical type from x. 

The precision level for y is set to 2. Therefore, y is initialized with 1.23. 

bcd(long double x, int decimals - Max); 

This constructor defines a bed variable from a variable that was previously 
declared to be a floating point long double type. Alternately, you can 
supply a long double value directly in the place of x. 

To specify a precision level (that is, the number of digits after the decimal 
point) that is different from the default, use the variable decimals. 

Friend functions 



real 



long double real (bed number) 

You can use the real function to convert a binary coded decimal number 
back to a long double. See the Programmer's Guide, Chapter 2, for a discus- 
sion about arithmetic conversions. 
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complex 



complex 



complex.h 



Constructor 



Constructor 



Creates complex numbers. Once you construct complex numbers, you can 
freely mix them in expressions with ints, doubles, and other numeric types. 
You can also use complex numbers in any of the ANSI C Standard mathe- 
matical functions. The ANSI math functions are documented in Chapter 2. 

The complex class also overloads the operators +, -, *, /, +=, -=, *=, /=, =, ==, 
and !=. These operators provide complex arithmetic manipulation in the 
usual sense. 

The operators « and » are overloaded for stream input and output of 
complex numbers, as they are for other data types in iostream.h. 

If you don't want to program in C++, but instead want to program in C, the 
only constructs available to you are struct complex and cabs, which give the 
absolute value of a complex number. Both of these alternates are defined in 
math.h. 

Public constructors 

complex () ; 

The default constructor. You typically use this to declare a variable of type 
complex. 

complex i; // Construct a complex-type number. 

complex j = 37; // Construct and initialize a complex-type number. 

complex (double real, double imag - 0); 

Creates a complex numerical type out of a double. Upon construction, a real 
and an imaginary part are provided. The imaginary part is considered to be 
zero if imag is omitted. 

Friend functions 



abs 



acos 



friend double abs(complex& val) ; 

Returns the absolute value of a complex number. 

The complex version of abs returns a double. All other math functions 
return a complex type when val is complex type. 

friend complex acos(complex& z) ; 
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complex 



Calculates the arc cosine. 

The complex inverse cosine is defined by 

acos(z) = -i * log(z + i sqrt(l - z 2 )) 

ar 9 double arg (complex x) ; 

arg gives the angle, in radians, of the number in the complex plane. 

The positive real axis has angle 0, and the positive imaginary axis has angle 
pi/2. If the argument passed to arg is complex (zero), arg returns zero. 

arg(x) returns atan2(imag(x), real(x)). 

as,n friend complex asin(complex& z) ; 

Calculates the arc sine. 
The complex inverse sine is defined by 

asin(z) = -i * log(i * z + sqrt(l - z 2 )) 
3t3n friend complex atan(complex& z) ; 

Calculates the arc tangent. 
The complex inverse tangent is defined by 

atan(z) = -0.5 i log((l + i z)/(l - i z) ) 
con J complex conj (complex z) ; 

Returns the complex conjugate of a complex number. 

conj(z) is the same as complex (real (z) , -imag(z)). 

cos friend complex cos(complex& z) ; 

Calculates the cosine of a value. 

The complex cosine is defined by 

cos(z) = ( exp(i * z) + exp(-i * z) ) / 2 
COS" friend complex cosh(complex& z) ; 

Calculates the hyperbolic cosine of a value. 

The complex hyperbolic cosine is defined by 
cosh(z) = ( exp(z) + exp(-z) ) / 2 
ex P friend complex exp(complex& y) ; 

Calculates the exponential e to the y. 
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complex 



The complex exponential function is defined by 

exp(x + y * i) = exp(x) (cos(y) + i * sin(y) ) 

,ma 9 double imag( complex x) ; 

Returns the imaginary part of a complex number. 

The data associated to a complex number consists of two floating-point 
(double) numbers, imag returns the one considered to be the imaginary 
part. 

'°9 friend complex log(complex& z) ; 

Calculates the natural logarithm of z. 

The complex natural logarithm is defined by 

log(z) = log( abs(z) ) + i * arg(z) 
Iog10 friend complex loglO(complex& z) ; 

Calculates log 10 (z). 
The complex common logarithm is defined by 

loglO(z) = log(z) / log(10) 
norm double norm (complex x); 

Returns the square of the absolute value. norm{x) returns the magnitude 

real(x) * real(x) + imag(x) * imag(x). 

norm can overflow if either the real or imaginary part is sufficiently large. 

P°' ar complex polar(double mag, double angle - 0); 

Returns a complex number with a given magnitude (absolute value) and 
angle. 

polar(mag, angle) is the same as compleximag * cos(angle), mag * sin(angle)). 

P ow friend complex pow(complex& base, double expon) ; 

friend complex pow(double base, complex& expon) ; 
friend complex pow(complex& base, complex^ expon) ; 

Calculates base to the power of expon. 

The complex pow is defined by 

powfbase, expon) - exp(expon * log(base)) 

rea ' double real (complex x) ; 

You can use the real function to convert a complex number back to a long 
double. The friend function returns the real part of a complex number or 
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complex 



sin 



converts a complex number back to double. The data associated to a 
complex number consists of two floating-point numbers, real returns the 
number considered to be the real part. 

See the Programmer's Guide, Chapter 2, for a discussion about arithmetic 
conversions. 



friend complex sin(complex& z) ; 

Calculates the trigonometric sine. 

The complex sine is defined by 

sin(z) = ( exp(i * z) - exp(-i * z) ) / (2 * i) 
Slnn friend complex sinh(complex& z) ; 

Calculates the hyperbolic sine. 

The complex hyperbolic sine is defined by 
sinh(z) = ( exp(z) - exp(-z) ) / 2 
Sqn friend complex sqrt (complex& x) ; 

Calculates the positive square root. 

For any complex number x, sqrt{x) gives the complex root whose org is 
arg(x)/2. 

The complex square root is defined by 

sqrt(x) = sqrt(abs(x)) (cos( arg(x) / 2) + i * sin(arg(x)/2) ) 
t an friend complex tan(complex& z) ; 

Calculates the trigonometric tangent. 
The complex tangent is defined by 
tan(z) = sin(z) / cos(z) 
t ann friend complex tanh(complex& z) ; 

Calculates the hyperbolic tangent. 
The complex hyperbolic tangent is defined by 
tanh(z) = sinh(z) / cosh(z) 
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To use DEBUG, 

you must link with the 
diagnostic libraries. 



Class diagnostic macros 



Borland provides a set of macros for debugging C++ code. These macros 
are located in checks.h. There are two types of macros, default and 
extended. The default macros are 



a CHECK 


□ TRACE 


h PRECONDITION 


a WARN 


The extended macros are 




a CHECKX 


hTRACEX 


ei PRECONDITIONX 


hWARNX 



The default macros provide straightforward value checking and message 
output. The extended macros let you create macro groups that you can 
selectively enable or disable. Extended macros also let you selectively 
enable or disable macros within a group based on a numeric threshold 
level. 

Three preprocessor symbols control diagnostic macro expansion: 
_ _DEBUG, _ JTRACE, and _ _WARN. If one of these symbols is defined 
when compiling, then the corresponding macros expand and diagnostic 
code is generated. If none of these symbols is defined, then the macros do 
not expand and no diagnostic code is generated. These symbols can be 
defined on the command line using the -D switch, or by using # define 
statements within your code. 

The diagnostic macros are enabled according to the following table: 





__DEBUG=1 


__DEBUG=2 


__TRACE 


__WARN 


PRECONDITION 


X 


X 






PRECONDITIONX 


X 


X 






CHECK 




X 






CHECKX 




X 






TRACE 






X 




TRACEX 






X 




WARN 








X 


WARNX 








X 



Chapter 8, Class diagnostic macros 



419 



To create a diagnostic version of an executable, place the diagnostic macros 
at strategic points within the program code and compile with the 
appropriate preprocessor symbols defined. Diagnostic versions of the 
Borland class libraries are built in a similar manner. 

The following sections describe the default and extended diagnostic 
macros, give examples of their use, and explain message output and run- 
time control. 



Default diagnostic macros 



checks.h 



CHECK CHECK (<cond>) 

Throws an exception containing the string <msg> if <cond> equals 0. Use 
CHECK to perform value checking within a function. 

PRECONDITION precondition ( <cond> ) 

Throws an exception containing the string <msg> if <cond> equals 0. Use 
PRECONDITION on entry to a function to check the validity of the 
arguments and to do any other checking to determine if the function has 
been invoked correctly. 

TRACE TRACE (<msg>) 

Outputs <msg>. TRACE is used to output general messages that are not 
dependent on a particular condition. 

WARN WARN(<cond>,<msg>) 

Outputs <msg> if <cond> is nonzero. It is used to output conditional 
messages. 

Example The following program illustrates the use of the default TRACE and 
WARN macros: 

Mnclude <checks.h> 

int main() 
{ 

TRACE ( "Hello World" ) ; 

WARN( 5 != 5, "Math is broken!" ); 

WARN( 5 != 7, "Math still works!" ); 



return 0; 



} 



When the above code is compiled with TRACE and WARN defined, it 

produces the following output when run: 
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Trace PROG.C 5: [Def] Hello World 
Warning PROG.C 7: [Def] Math still works! 

The above output indicates that the message "Hello World" was output by 
the default TRACE macro on line 5 of PROG.C, and the message "Math still 
works!" was output by the default WARN macro on line 7 of PROG.C. 

Default diagnostic macros expand to extended diagnostic macros with the 
group set to "Def" and the level set to 0. This "Def" group controls the 
behavior of the default macros and is initially enabled with a threshold 
level of 0. 



Extended diagnostic macros 



checks.h 



CHECKX 



PRECONDITION 



TRACEX 



WARNX 



The extended macros CHECKX and PRECONDITIONX augment CHECK 
and PRECONDITION by letting you provide a message to be output when 
the condition fails. 

The extended macros TRACEX and WARNX augment TRACE and WARN 
by providing a way to specify macro groups that can be independently 
enabled or disabled. TRACEX and WARNX require additional arguments 
that specify the group to which the macros belongs, and the threshold level 
at which the macro should be executed. The macro is executed only if the 
specified group is enabled and has a threshold level that is greater than or 
equal to the threshold-level argument used in the macro. 

The following sections describe the extended diagnostic macros. 

CHECKX (<cond>,<msg>) 

Throws an exception containing the string <msg> if <cond> equals 0. Use 
CHECKX to perform value checking within a function. 

PRECONDITIONX ( <cond> , <msg> ) 

Throws an exception containing the string <msg> if <cond> equals 0. Use 
PRECONDITIONX on entry to a function to check the validity of the 
arguments and to do any other checking to determine if the function has 
been invoked correctly. 

TRACEX (<group>, <level>, <msg>) 

Trace only if <group> and <level> are enabled. 

WARNX (<group>,<cond>,<level>,<msg>) 

Warn only if <group> and <level> are enabled. 
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Extended diagnostic macros 



When using TRACEX and WARNX you need to be able to create groups. 
The following three macros create diagnostic macro groups: 



DIAG_DECLARE_GROUP DIAG_DECLARE_GROUP(<name>) 

Declare a group named <name>. You cannot use DIAG_DEFINE_GROUP 
and DIAG_DECLARE_GROUP in the same compilation unit. Multiple 
group declarations in the same compilation unit are allowed. 

If a header file uses DIAG_DECLARE_GROUP (so that the group declara- 
tion is automatically available to files that include the header), the source 
file that contains the DIAG_DECLARE_GROUP invocation for that group 
then generates a redefinition error. The solution is to conditionalize the 
header file so that the declaration goes away when the source file with the 
DIAG_DECLARE_GROUP invocation is built. 

For example, in myheader.h 

#if ! defined) BUILD_MY_GROUP ) 

DIAG_DECLARE_GROUP 

#endif 

And in the source file my_prog.cpp: 

#define BUILD_MY_GROUP 
# include "myheader.h" 

DIAG_DEFINE_GROUP ,DIAG_DEFINEJ3R0UP(<name>,<enabled>,<level>) 

Define a group named <name>. You cannot use DIAG_DEFINE_GROUP 
and DIAG_DECLARE_GROUP in the same compilation unit. 



DIAG ENABLE 



DIAG ISENABLED 



The following two macros manipulate groups: 

DIAG_ENABLE (<group>, <state>) 

Sets <group>'s enable flag to <state>. 

DIAG_ISENABLED (<group>) 

Returns nonzero if <group> is enabled. 



DIAG SETLEVEL 



DIAG GETLEVEL 



The following two macros manipulate levels: 

DIAG_SETLEVEL (<group>,<level>) 

Sets <group>'s threshold level to <level>. 

DIAG_GETLEVEL (<group>) 

Gets <group>'s threshold level. 
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Threshold levels are arbitrary numeric values that establish a threshold for 
enabling macros. A macro with a level greater than the group threshold 
level its test will be performed, but it won't display anything. For example, 
if a group has a threshold level of (the default value), all macros that 
belong to that group and have levels of 1 or greater are ignored. 

Example The following PROG.C example defines two diagnostic groups, Groupl and 
Group!, which are used as arguments to extended diagnostic macros: 

♦include <checks.h> 

DIAG_DEFINE_GROUP (Groupl, 1, 0); 
DIAG_DEFINE_GR0UP(Group2, 1, 0); 

int main( int argc, char **argv ) 
{ 

TRACE ( "Always works, argc=" « argc ) ; 

TRACEX( Groupl, 0, "Hello" ) ; 

TRACEX( Group2, 0, "Hello" ); 

DIAG_ENABLE (Groupl , ) ; 

TRACEX( Groupl, 0, "Won't execute - group is disabled!" ) ; 
TRACEX( Group2, 3, "Won't execute - level is too high!" ); 

return 0; 
} 

When the above code is compiled with TRACE defined and run, it 

produces the following output: 

Trace PROG.C 8: [Def] Always works, argc=l 
Trace PROG.C 10: [Groupl] Hello 
Trace PROG.C 11: [Group2] Hello 

Note that the last two macros are not executed. In the first case, the group 
Groupl is disabled. In the second case, the macro level exceeds Group2's 
threshold level (set by default to 0). 



Macro message output 



The TRACE, TRACEX, WARN, and WARNX macros take a <msg> 
argument that is conditionally inserted into an output stream. This means a 
sequence of objects can be inserted in the output stream (for example TRACE ( 
"Mouse @ " « x « " , " « y ) ; ). The use of streams is extensible to 
different object types and allows for parameters within trace messages. 
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Run-time macro control 



Diagnostic groups can be controlled at run time by using the control 
macros described above within your program or by directly modifying the 
group information within the debugger. 

This group information is contained in a class named TDiagGroup< 
TDiagGroupClass##Group >, where ##Group is the name of the group. This 
class contains a static structure Flags, which in turn contains the enabled 
flag and the threshold level. For example, to enable the group Groupl, you 
would set the variable TDiagGroup<TDiagGroupClassGroupl>::Flags. Enabled 
tol. 
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Run-time support 



This chapter provides a detailed description, in alphabetical order, of 
functions and classes that provide run-time support. Any class operators or 
member functions are listed immediately after the class constructor. See the 
Programmer's Guide, Chapter 4, for a discussion of how to use exception- 
handling keywords. 

The portability for all classes and functions in this chapter is as follows: 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 




■ 





Bad cast class 



typeinfo.h 



When dynamic_cast fails to make a cast to reference, the expression can 
throw Bad_cast. Note that when dynamic_cast fails to make a cast to 
pointer type, the result is the null pointer. 



Badjypeid class 



typeinfo.h 



When the operand of typeid is a dereferenced pointer, the typeid operator 
can throw Badjtypeid. 



set new handler function 



new.h 



typedef void (new * newjiandler) () throw (xalloc ) ; 
new_handler set_new_handler (newjiandler myjiandler) ; 

set_new_handler installs the function to be called when the global operator 
new() or operator new[]() cannot allocate the requested memory. By default 
the new operators throw an xalloc exception if memory cannot be allocated. 
You can change this default behavior by calling set_newjiandler to set a 
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set new handler function 



new handler. To retain the traditional version of new, which does not throw 
exceptions, you can use set_nezu_handler(0). 

If new cannot allocate the requested memory, it calls the handler that was 
set by a previous call to setjnewjiandler. If there is no handler installed by 
set_new_handler, new returns 0. myjiandler should specify the actions to be 
taken when new cannot satisfy a request for memory allocation. The 
newjiandler type, defined in new.h, is a function that takes no arguments 
and returns void. A newjiandler can throw an xalloc exception. 

The user-defined myjiandler should do one of the following: 

■ Return after freeing memory 

■ Throw an xalloc exception or an exception derived from xalloc 

■ Call abort or exit functions 

If myjiandler returns, then new will again attempt to satisfy the request. 

Ideally, myjiandler frees up memory and returns; new can then satisfy the 
request and the program can continue. However, if myjiandler cannot 
provide memory for new, myjiandler must throw an exception or terminate 
the program. Otherwise, an infinite loop will be created. 

Preferably, you should overload operator new() and operator new[]() to 
take appropriate actions for your applications. 

setjiewjiandler returns the old handler, if one has been registered. 

The user-defined argument function, myjiandler, should not return a value. 

See also the description of abort, exit, and jiewjiandler (global variable). 

setjerminate function except.h 

typedef void ( *terminate_f unction) () ; 

terrainate_function set_terminate(terrainate_f unction t_func) ; 

setjerminate lets you install a function that defines the program's termina- 
tion behavior when a handler for the exception cannot be found. The 
actions are defined in tjunc, which is declared to be a function of type 
terminate Junction. A terminate Junction type, defined in except.h, is a 
function that takes no arguments, and returns void. 

By default, an exception for which no handler can be found results in the 
program calling the terminate function. This will normally result in a call to 
abort. The program then ends with the message Abnormal program 
termination. If you want some function other than abort to be called by the 
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terminate function, you should define your own tjunc function. Your tjunc 
function is installed by setjterminate as the termination function. The instal- 
lation of tjunc lets you implement any actions that are not taken by abort. 

The previous function given to setjerminate will be the return value. 

The definition of tjunc must terminate the program. Such a user-defined 
function must not return to its caller, the terminate function. An attempt to 
return to the caller results in undefined program behavior. It is also an error 
for tjunc to throw an exception. 

See also the description of abort, set_unexpected, and terminate. 

setjjnexpected function except.h 

typedef void ( * unexpected_function )(); 

unexpected_f unction set_unexpected(unexpected_f unction unexpected_func) ; 

set_unexpected lets you install a function that defines the program's behavior 
when a function throws an exception not listed in its exception specifica- 
tion. The actions are defined in unexpected June, which is declared to be a 
function of type unexpected Junction. An unexpected Junction type, defined in 
except.h, is a function that takes no arguments, and returns void. 

By default, an unexpected exception causes unexpected to be called. If 
unexpected June is defined, it is subsequently called by unexpected. Program 
control is then turned over to the user-defined unexpected June. Otherwise, 
terminate is called. 

The previous function given to set_unexpected will be the return value. 

The definition of unexpected June must not return to its caller, the unexpected 
function. An attempt to return to the caller results in undefined program 
behavior. 

unexpected June can also call abort, exit, or terminate. 

See also the description of abort, exit, set terminate, and terminate. 

terminate function except.h 

void terminate ( ) ; 

The function terminate can be called by unexpected or by the program when 
a handler for an exception cannot be found. The default action by terminate 
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is to call abort. Such a default action causes immediate program 
termination. 

You can modify the way your program terminates when an exception is 
generated that is not listed in the exception specification. If you don't want 
the program to terminate with a call to abort, you can instead define a 
function to be called. Such a function (called a terminate _f unction) will be 
called by terminate if it is registered with setjerminate. 

The function does not return. 

See also the description of abort and setjerminate. 



Typejnfo class 



typeinfo.h 



Provides information about a type. 



Public constructor 



Constructor None. 

Only a private constructor is provided. You cannot create Typejnfo objects. 

By declaring your objects to be rtti types, or by using the -RT compiler 

switch, the compiler provides your objects with the elements of Typejnfo. 

Typejnfo references are generated by the typeid operator. See Chapter 2 in 
the Programmer's Guide for a discussion of typeid. 



Operators 



operator == j_ n t operator== (const Type_info &) const; 

Provides comparison of Typeinfos. 
operator != int operator != (const Type_info &) const; 

Provides comparison of Typeinfos. 

Public member functions 



before 



int before (const Type_info &); 

Use this function to compare the lexical order of types. For example, to 
compare two types, T1 and 72, use the following syntax: 
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name 



typeidt Tl ) .before (typeid( T2 )); 
The before function returns or 1. 

const char* name() const; 

The name function returns a printable string that identifies the type name of 
the operand to typeid. The space for the character string is overwritten on 
each call. 



unexpected function 



excepth 



void unexpected () ; 

The unexpected function is called when a function throws an exception not 
listed in its exception specification. The program calls unexpected, which by 
default calls any user-defined function registered by set_unexpected. If no 
function is registered with setjunexpected, the unexpected function then calls 
terminate. 

The unexpected function does not return. However, the function can throw 
an exception. 

See also the description of setjunexpected and terminate. 



xalloc class 



except.h 



Reports an error on allocation request. 



Public constructors 



Constructor xalloc (const string &msg, size_t size); 

The xalloc class has no default constructor. Every use of xalloc must define 
the message to be reported when a size allocation cannot be fulfilled. The 
string type is defined in cstring.h header file. 



Public member functions 



raise 



requested 



void raised throw(xalloc) ; 

Calling raise causes an xalloc to be thrown. In particular, it throws *this. 

size_t requested () const; 
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Returns the number of bytes that were requested for allocation. 



xmsg class 



except.h 



Reports a message related to an exception. 



Public constructor 



Constructor 



xmsg (string msg) ; 

There is no default constructor for xmsg. Every xmsg object must have a 
string message explicitly defined. The string type is defined in cstring.h 
header file. 



raise 



why 



Public member functions 

void raised throw(xmsg); 

Calling raise causes an xmsg to be thrown. In particular, it throws *this. 

string why() const; 

Reports the string used to construct an xmsg. Because every xmsg must 
have its message explicitly defined, every instance should have a unique 
message. 
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C++ utility classes 



This chapter is a reference guide for the following classes, which are listed 
here with their associated header-file names: 



i Date class 
i File classes 
i String classes 
Threading classes 
Time classes 



BCOS2\INCLUDE\CLASSLIB\date.h 

BCOS2\INCLUDE\CLASSLIB\file.h 

BCOS2\INCLUDE\cstring.h 

BCOS2\INCLUDE\CLASSLIB\thread.h 

BCOS2\INCLUDE\CLASSLIB\time.h 



TDate class 



date.h 



class TDate 

Class TDate represents a date. It has members that read, write, and store 
dates, and that convert dates to Gregorian calendar dates. 



DayTy 

HowToPrint 

JulTy 

MonthTy 

YearTy 



Type definitions 



typedef unsigned DayTy; 

Day type. 

enum HowToPrint { Normal, Terse, Numbers, EuropeanNumbers, European }; 

Lists different print formats. 

typedef unsigned long JulTy; 

Julian calendar type. 

typedef unsigned MonthTy; 

Month type. 

typedef unsigned YearTy; 

Year type. 
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Public constructors 



Constructor 



Constructor 



Constructor 



Constructor 



Constructor 



AsString 
Between 
CompareTo 

Day 
DayName 

DayOfMonth 



TDateO; 

Constructs a TDate object with the current date. 

TDate ( DayTy day, YearTy year ); 

Constructs a TDate object with the given day and year. The base date for this 
computation is Dec. 31 of the previous year. If year == 0, it constructs a 
TDate with Jan. 1, 1901 as "day zero." For example, TDate(-l,0) = Dec. 31, 
1900 and TDate(l,0) = Jan. 2, 1901. 

TDate ( DayTy day, const char* month, YearTy year); 
TDate ( DayTy day, MonthTy month, YearTy year); 

Constructs a TDate object for the given day, month, and year. 

TDate ( istreamk is ) ; 

Constructs a TDate object, reading the date from input stream is. 

TDate ( const TTimek time); 

Constructs a TDate object from TTime object time. 

Public member functions 

string AsString () const; 

Converts the TDate object to a string object. 

int Between ( const TDatek dl, const TDatek d2 ) const; 
Returns 1 if this TDate object is between dl and dl, inclusive. 

int CompareTo ( const TDate & ) const; 

Returns 1 if the target TDate is greater than parameter TDate, -1 if the target 
is less than the parameter, and if the dates are equal. 

DayTy Day() const; 

Returns the day of the year (1-365). 

const char *DayName( DayTy weekDayNumber ); 

Returns a string name for the day of the week, where Monday is 1 and 
Sunday is 7. 

DayTy DayOfMonth () const; 

Returns the day of the month (1-31). 
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DayOfWeek 

DayslnYear 

DayWithinMonth 

FirstDayOfMonth 



Hash 



IndexOfMonth 



IsValid 



Jday 



Leap 



Max 



Min 



Month 



DayTy DayOfWeek ( const char* dayName ); 

Returns the number associated with a string naming the day of the week, 
where Monday is 1 and Sunday is 7. 

DayTy DayslnYear ( YearTy ); 

Returns the number of days in the specified year (365 or 366). 

int DayWithinMonth ( MonthTy, DayTy, YearTy ); 

Returns 1 if the given day is within the given month for the given year. 

DayTy FirstDayOfMonth () const; 

Returns the number of the first day of the month for this TDate. 

DayTy FirstDayOfMonth ( MonthTy month) const; 

Returns the number of the first day of a given month. Returns if month is 
outside the range 1 through 12. 

unsigned Hash() const; 

Returns a hash value for the date. 

MonthTy IndexOfMonth ( const char *monthName ); 

Returns the number (1-12) of the month monthname. 

int IsValid () const; 

Returns 1 if this TDate is valid, otherwise. 

JulTy Jday( MonthTy, DayTy, YearTy ); 

Converts the given Gregorian calendar date to the corresponding Julian 
day number. Gregorian calendar started on Sep. 14, 1752. This function not 
valid before that date. Returns if the date is invalid. 

int Leap() const; 

Returns 1 if this TDate's year is a leap year, otherwise. 

TDate Max( const TDate& dt ) const; 

Compares this TDate with dt and returns the date with the greater Julian 
number. 

TDate Min( const TDate& dt ) const; 

Compares this TDate with dt and returns the date with the lesser Julian 
number. 

MonthTy Month () const; 
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MonthName 



NameOfDay 



NameOfMonth 



Previous 



SetPrintOption 

WeekDay 
Year 



Returns the month number for this TDate. 

const char *MonthName ( MonthTy monthNumber ) ; 

Returns the string name for the given monthNumber (1-12). Returns for an 
invalid monthNumber. 

const char *NameOfDay() const; 

Returns this TDate's day string name. 

const char *NameOf Month ( ) const; 

Returns this TDate's month string name. 

TDate Previous ( const char *dayName ) const; 

Returns the TDate of the previous dayName. 

TDate Previous! DayTy day ) const; 

Returns the TDate of the previous day. 

HowToPrint SetPrintOption ( HowToPrint h ); 

Sets the print option for all TDate objects and returns the old setting. See 
HowToPrint in the "Type definition" section for this class. 

DayTy WeekDay () const; 

Returns 1 (Monday) through 7 (Sunday). 

YearTy Year() const; 

Returns the year of this TDate. 

Protected member functions 



AssertlndexOfMonth static int AssertlndexOf Month ( MonthTy m ); 

Returns 1 if m is between 1 and 12 inclusive, otherwise returns 0. 
AssertWeekDayNumber static int AssertWeekDayNumber( DayTy d) ; 

Returns 1 if d is between 1 and 7 inclusive, otherwise returns 0. 



Operator < 
Operator <= 



Operators 



int operator < ( const TDatek date ) const; 

Returns 1 if this TDate precedes date, otherwise returns 0. 

int operator <= ( const TDatek date ) const; 
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Returns 1 if this TDate is less than or equal to date, otherwise returns 0. 

Operator > i n t operator > ( const TDate& date ) const; 

Returns 1 if this TDate is greater than date, otherwise returns 0. 
Operator >= int operator >= ( const TDate& date ) const; 

Returns 1 if this TDate is greater than or equal to date, otherwise returns 0. 
Operator == i n t operator == ( const TDatek date ) const; 

Returns 1 if this TDate is equal to date, otherwise returns 0. 
Operator != i n t operator != ( const TDatek date ) const; 

Returns 1 if this TDate is not equal to date, otherwise returns 0. 
Operator- JulTy operator - ( const TDatek dt ) const; 

Subtracts dt from this TDate and returns the difference. 

Operator + friend TDate operator + ( const TDateSc dt, int dd ); 

friend TDate operator + ( int dd, const TDatek dt ) ; 

Returns a new TDate containing the sum of this TDate and dd. 

Operator- friend TDate operator - ( const TDatek dt, int dd ); 

Subtracts dd from this TDate and returns the difference. 
Operator ++ . vo id operator ++ ( ) ; 

Increments this TDate by 1. 
Operator — vo id operator -- (); 

Decrements this TDate by 1. 
Operator += vo id operator += ( int dd ) ; 

Adds dd to this TDate. 
Operator -= void operator -= ( int dd ); 

Subtracts dd from this TDate. 
Operator « friend ostream& operator « ( ostream& os, const TDate& date ); 

Inserts date into output stream os. 
Operator » friend istream& operator » ( istreamk is, TDate& date ); 

Extracts date from input stream is. 
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TFileStatus structure file.h 

struct TFileStatus 
{ 

TTime createTime; 

TTime modifyTime; 

TTime accessTime; 

long size; 

uint8 attribute; 

char fullName[_MAX_PATH]; 
}; 

Describes a file record containing creation, modification, and access times; 
also provides the file size, attributes, and name. 

See also: TTime class 

TFile class file.h 

class TFile 

Class TFile encapsulates standard file characteristics and operations. 



FileNull 



File flags 



Public data members 



enum { FileNull }; 


Represents a : 


null file handle. 


enum{ 




Readonly 


= 0_RD0NLY, 


ReadWrite 


= 0_RDWR, 


WriteOnly 


= 0_WR0NLY, 


Create 


= 0_CREAT | 0_TRUNC, 


CreateExcl 


= 0_CREAT I 0_EXCL, 


Append 


= 0_APPEND, 


Corapat 


=-SH_C0MPAT, 


DenyNone 


= SH_DENYNONE, 


DenyRdWr 


= SH_DENYRW, 


Nolnherit 
}; 


= 0_NOINHERIT 



Enumerates file-translation modes and sharing capabilities. See the open 
and sopen functions in Chapter 2. 
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enum{ 






PermRead 


= S_IREAD, 




PermWrite 


= S_IWRITE, 




PermRdWr 
}; 


= S_IREAD I 


S_IWRITE 



Enumerates file read and write permissions. See the creat function in 
Chapter 2. 



enum{ 




Normal 


= 0x00, 


RdOnly 


= 0x01, 


Hidden 


= 0x02, 


System 


= 0x04, 


Volume 


= 0x08, 


Directory 


= 0x10, 


Archive 


= 0x20 



}; 

Enumerates file types. 

enum seek_dir 
{ 

beg = 0, 
cur = 1, 
end = 2 
}; 

Enumerates file-pointer seek direction. 



Public constructors 



Constructor TFile (),- 

Creates a TFile object with a file handle of FileNull. 
Constructor TF ii e ( int handle ); 

Creates a TFile object with a file handle of handle. 
Constructor TFile ( const TFile& file ); 

Creates a TFile object with the same file handle file. 

Constructor TFile ( const char* name, uintl6 access=ReadOnly, 

uintl6 permission=PermRdWr ) ; 

Creates a TFile object and opens file name with the given attributes. The file 
is created if it doesn't exist. 
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Public member functions 



Close 



Flush 



GetHandle 



GetStatus 



IsOpen 
Length 



LockRange 



Open 



Position 



Read 



int Close ( ) ; 

Closes the file. Returns nonzero if successful, otherwise. 

void Flush () ; 

Performs any pending I/O functions. 

int GetHandle () const; 
Returns the file handle. 

int GetStatus ( TFileStatusk status ) const; 

Fills status with the current file status. Returns nonzero if successful, 
otherwise. 

int GetStatus ( const char *name, TFileStatusk status ); 

Fills status with the status for file name. Returns nonzero if successful, 
otherwise. 

int IsOpen () const; 

Returns 1 if the file is open, otherwise. 

long Length () const; 

Returns the file length. 

void Length ( long newLen ); 

Resizes file to newLen. 

void LockRange ( long position, uint32 count ); 

Locks count bytes, beginning at position of the associated file. 

See also: UnlockRange 

int Open( const char* name, uintl6 access, uintl6 permission ); 

Opens file name with the given attributes. The file will be created if it 
doesn't exist. Returns 1 if successful, otherwise. 

long Position () const; 

Returns the current position of the file pointer. Returns -1 to indicate an 
error. 

int Read( void *buffer, int numBytes ); 

Reads numBytes from the file into buffer. 
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Remove 

Rename 

Seek 

SeekToBegin 

SeekToEnd 

SetStatus 

UnlockRange 

Write 

string class 



StripType 



static void Remove ( const char *name ); 

Removes file name. Returns if successful, -1 if unsuccessful. 

static void Rename ( const char *oldName, const char *newName ); 

Renames file oldName to newName. 

long Seek( long offset, int origin = beg ); 

Repositions the file pointer to offset bytes from the specified origin. 

long SeekToBegin ( ) ; 

Repositions the file pointer to the beginning of the file. 

long SeekToEnd ( ) ; 

Repositions the file pointer to the end of the file. 

static int SetStatus ( const char *name, const TFileStatusk status ); 

Sets file name's status to status. 

void UnlockRange (long Position, uint32 count ); 

Unlocks the range at the given Position. 

See also: LockRange 

int Write ( const void *buffer, int numBytes ); 

Writes numbytes of buffer to the file. 



cstring.h 



class string 

This class uses a technique called "copy-on-write." Multiple instances of a 
string can refer to thesame piece of data so long as it is in a "read-only" 
situation. If a string writes to the data, a copy is automatically made if more 
than one string is referring to it. 



Type definitions 



enum StripType { Leading, Trailing, Both }; 

Enumerates type of stripping. See strip in the "Public member functions' 
section for this class. 
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Public constructors and destructor 



Constructor 



Constructor 



Constructor 



Constructor 



Constructor 



Constructor 



Constructor 



Constructor 



Constructor 



string (); 

The default constructor. Creates a string of length zero. 

string(const string &s); 

Copy constructor. Creates a string that contains a copy of the contents of 
string s. 

string ( const string &s, size_t start, size_t n = NPOS ) 

Creates a string containing a copy of the n bytes beginning at position start 
of string s. 

string(const char *cp) ; 

Creates a string containing a copy of the bytes from the location pointed to 
by cp through the first byte (conversion from char*). 

string( const char *cp, size_t start, size_t n = NPOS ); 

Creates a string containing a copy of the n bytes beginning at the position 
start in the buffer pointed to by cp. 

II Construct a string object from a char buffer, 
ttinclude <cstring.h> 
ttinclude <iostream.h> 

int main (void) { 

const char *cp = "0123456789"; 
string sl(cp, 3, 5) ; 

cout « "si = " « si; 

return 0; 

} 

Program output: 

si = 34567 

string ( char c ) 

Constructs a string containing the character c. 

string ( char c, size_t n ) 

Constructs a string containing the character c repeated n times. 

string! signed chare ) 

Constructs a string containing the character c. 

string ( signed char c, size_t n ) 
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Constructor 



Constructor 



Constructor 



Destructor 



Constructs a string containing the character c repeated n times. 

string( unsigned char c ) 

Constructs a string containing the character c. 

string ( unsigned char c, size_t n ) 

Constructs a string containing the character c repeated n times. 

string(const TSubString &ss) ; 

Constructs a string from the substring ss. 

-string () ; 

Frees all resources allocated to this object. 



Public member functions 



append 



assign 



string & append ( const string &s ) 
Appends string s to the target string. 

string & append ( const string &s, size_t start, size_t n = NPOS) 

Beginning from the start position in s, the append function appends the next 
n characters of string s to the target string. 

string & append ( const char *cp, size_t start, size_t n = NPOS ) 

Beginning from the start position of the character array cp, the append 
function appends the next n characters to the target string. 

string & assign ( const string &s ); 

Assigns string s to target string. 

See also: operator = 

string & assign ( const string &s, size_t start, size_t n = NPOS ); 

Beginning from the start position in s, the assign function copies n 
characters to target string. For example: 

string si = "abcdef"; 

string s2; 

s2. assign ( si, 2, 3 ) ; 

Results in s2 set to cde. 
See also: operator = 
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compare 



contains 



copy 



c str 



find 



int compare (const string &s); 

Compares the target string to the string s. compare returns an integer less 
than, equal to, or greater than 0, depending on whether the target string is 
less than, equal to, or greater than s. 

int compare ( const string &s, size_t start, size_t n = NPOS ); 
Beginning as position start in s, the compare function compares not more 
than n characters from the target string to the string s. The compare function 
returns a negative value if the string compares less than the argument, if 
they compare equal, and positive if greater than. 

int contains (const char * pat) const; 

Returns 1 if pat is found in the target string, otherwise. 

int contains (const string & s) const; 

Returns 1 if string s is found in the target string, otherwise. 

size_t copy( char *cb, size_t n ) 

Copies at most n characters from the target string into the char array 
pointed to by cb. copy returns the number of characters copied. 

size_t copy( char *cb, size_t n, size_t pos ) 

Copies at most n characters beginning at position pos from the target string 
into the char array pointed to by cb. copy returns the number of characters 
copied. 

string copy() const throw ( xalloc ). 

Returns a distinct copy of the string. 

const char *c_str() const; 

Returns a pointer to a zero-terminated character array that holds the same 
characters contained in the string. The returned pointer might point to the 
actual contents of the string, or it might point to an array that the string 
allocates for this function call. The effects of any direct modification to the 
contents of this array are undefined, and the results of accessing this array 
after the execution of any non-const member function on the target string 
are undefined. 

Conversions from a string object to a char* are inherently dangerous, 
because they violate the class boundary and can lead to dangling pointers. , 
For this reason class string does not have an implicit conversion to char*, 
but provides c_str for use when this conversion is needed. 

size_t find( const string &s ) 
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Locates the first occurrence of the string s in the target string. If the string is 
found, it returns the position of the beginning of s within the target string. 
If the string s is not found, it returns NPOS. 

size_t find( const string &s, size_t pos ) 

Locates the first occurrence of the string s in the target string, beginning at 
the position pos. If the string is found, it returns the position of the 
beginning of s within the target string. If the s is not found, it returns NPOS 
and does not change pos. 

size_t find( const TRegexp &pat, size_t i = ) 

Searches the string for patterns matching regular expression pat beginning 
at location i. It returns the position of the beginning of pat within the target 
string. If the pat is not found, it returns NPOS and does not change pos. 

size_t find( const TRegexp &pat, size_t *ext, size_t i = ) const; 

Searches the string for patterns matching regular expression pat beginning 
at location i. Parameter ext returns the length of the matching string if 
found. It returns the position of the beginning of pat within the target 
string. If the pat is not found, it returns NPOS and does not change pos. 

See also: rfind 

find_first_of size_t find_first_of ( const string &s ) const; 

Locates the first occurrence in the target string of any character contained 
in string s. If the search is successful findJtrst_of returns the character 
location. If the search fails find_first_of returns NPOS. 

size_t find_first_of ( const string &s, size_t pos ) const; 

Locates the first occurrence in the target string of any character contained 
in string s after position pos. If the search is successful, the function returns 
the character position within the target string. If the search fails or if pos > 
length ( ) , find _first_of returns NPOS. 

find_first_not_OT size_t find_first_not_of( const string &s) const; 

Locates the first occurrence in the target string of any character not 
contained in string s. If the search is successful, find_first_not_of returns the 
character position within the target string. If the search fails it returns 
NPOS. 

size_t f ind_f irst_not_of ( const string &s, size_t pos ) const; 

Locates the first occurrence in the target string of any character not 
contained in string s after position pos. If the search is successful 
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find_first_not_of returns the character position within the target string. If the 
search fails or if pos > lengthO, find Jirst_not_of returns NPOS. 

find_last_OT size_t f ind_last_of ( const string &s ) const; 

Locates the last occurrence in the target string of any character contained in 
string s. If the search is successful find_last_of returns the character position 
within the target string. If the search fails it returns 0. 

size_t f ind_last_of ( const string &s, size_t pos ) const; 

Locates the last occurrence in the target string of any character contained in 
string s after position pos. If the search is successful find_last_of returns the 
character position within the target string. If the search fails or if pos > 
length(),find_last_of returns NPOS. 

find_last_not_Oi size_t f ind_last_not_of ( const string &s ) const; 

Locates the last occurrence in the target string of any character not 
contained in string s. If the search is successful find_last_not_of returns the 
character position within the target string. If the search fails it returns 
NPOS. 

size_t f ind_last_not_of ( const string &s, size_t pos ) const; 

Locates the last occurrence in the target string of any character not 
contained in string s after position pos. If the search is successful 
find_last_not_of returns the character position within the target string. If the 
search fails or if pos > length(),find_last_not_of returns NPOS. 

9©t_at char get_at( size_t pos ) const throw( outofrange ); 

Returns the character at the specified position. If pos > length ( ) -1, an 
outofrange exception is thrown. 

See also: put_at 
g6t_case_S6nsitive_flag static int get_case_sensitiveFlag() 

Returns if string comparisons are case sensitive, 1 if not. 
get_initial_capacity static unsigned get_initial_capacity() 

Returns the number of characters that will fit in the string without resizing. 
get_max_waste static unsigned get_max_waste() 

After a string is resized, returns the amount of free space available. 
get_paranoid_check static int get_paranoid_check ( ) ; 

Returns 1 if paranoid checking is enabled, if not. 
get_resize_increment static unsigned get_resize_increment() 
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Returns the string resizing increment. 

get_Skipwhitespace_flag static int get_skipwhitespace_flag() 
Returns 1 if whitespace is skipped, if not. 

hash unsigned hash() const; 

Returns a hash value. 
initial_capacity static size_t initial_capacity(size_t ic = 

Sets initial string allocation capacity. 

string &insert( size_t pos, const string 



insert 



is null 



length 



max waste 



prepend 



63! 



&s 



Inserts string s at position pos in the target string, insert returns a reference 
to the resulting string. 

string &insert( size_t pos, const string &s, size_t start, 
size_t n = NPOS ) 

Beginning as position start in s, the insert function inserts not more than n 
characters from the target string to the string s at position pos. insert returns 
a reference to the resulting string. If pos is invalid, insert throws the 
outofrange exception. 

int is_null() const; 

Returns 1 if the string is empty, otherwise. 

unsigned length () const; 

Returns the number of characters in the target string. Since null characters 
can be stored in a string, length ( ) might be greater than strlen (c_str ( ) ) . 

static size_t MaxWaste(size_t raw = 63); 

Sets the maximum empty space size and resizes the string. 

string &prepend( const string &s ) 
Prepends string s to the target string. 

string &prepend( const string &s, size_t start, size_t n = NPOS ) 

Beginning from the start position in s, the prepend function prefixes the 
target string with n characters taken from string s. 

string si - "abcdef"; 
string s2 = "0123"; 
s2. prepend ( si, 2, 3 ) ; 

Results in s2 set to cde0123. 
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string &prepend( const char *cp ) 

Prepends the character array cp to the target string. 

string &prepend( const char *cp, sizes_t start, size_t n = NPOS ) 

Beginning from the start position in cp, the prepend function prefixes the 
target string with n characters taken from character array cp. 

put_at void put_at( size_t pos, char c ) throw ( outof range ); 

Replaces the character at pos with c. If pos == length ( ) , put At appends c to 
the target string. If pos > length ( ) an outofrange exception is thrown. 

read_flle istream &read_file( istream &is); 

Reads from input stream is until an EOF or a null terminator is reached. 
readjine istream &read_line( istream &is); 

Reads from input stream is until an EOF or a newline is reached. 
read_Siring istream &read_string( istream &is); 

Reads from input stream is until an EOF or a null terminator is reached. 
read_tO_delim istream &read_to_delim( istream &is, char del im = '\n'); 

Reads from input stream is until an EOF or a delim is reached. 

readjoken istream &read_token (istream &is) ; 

Reads from input stream is until whitespace is reached. Note that this 
function skips any initial whitespace. 

n'nd size_t rfind( const string &s ) 

Locates the last occurrence of the string s in the target string. If the string is 
found, it returns the position of the beginning of the string s within the 
target string. If s is not found, it returns NPOS. 

size_t rfind( const string &s, size_t pos ) 

Locates the last occurrence of the string s that is not beyond the position pos 
in the target string. If the string is found, it returns the position of the 
beginning of s within the target string. If s is not found, it returns NPOS 
and does not change pos. 



remove 



See also: find 

string &remove( size_t pos ); 

Removes the characters from pos to the end of the target string and returns 
a reference to the resulting string. 
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replace 



reserve 



resize 



resize increment 



set case sensitive 



set_paranoid_check 



skip_whitespace 



strip 



string &remove( size_t pos, size_t n ) 

Removes at most n characters from the target string beginning at pos and 
returns a reference to the resulting string. 

string &replace( size_t pos, size_t n, const string &s ) 

Removes at most n characters from the target string beginning at pos, and 
replaces them with a copy of the string s. replace returns a reference to the 
resulting string. 

string &replace( size_t pos, size_t nl, const string &s, size_t start, 
size_t n2 = NPOS ) 

Removes at most nl characters from the target string beginning at pos, and 
replaces them with nl characters of string s beginning at start, replace 
returns a reference to the resulting string. 

size_t reserve () const; 

Returns an implementation-dependent value that indicates the current 
internal storage size. The returned value is always greater than or equal to 

lengthf). 

void reserve! size_t ic ) 

Suggests to the implementation that the target string might eventually 
require ic bytes of storage. 

void resize(size_t m) ; 

Resizes the string to m characters, truncating or adding blanks as necessary. 

static size_t resize_increment(size_t ri = 64); 

Sets the resize increment for automatic resizing. 

static int set_case_sensitive(int tf = 1); 

Sets case sensitivity. 1 is case sensitive; is not case sensitive. 

static int set_paranoid_check(int ck = 1); 

String searches use a hash value scheme to find the strings. There is a 
possibility that more than one string could hash to the same value. Calling 
set_paranoid_check with ck set to 1 forces checking the string found against 
the desired string with the C library function strcmp. When 
set_paranoid_check is called with ck set to 0, this final check isn't made. 

static int skip_whitespace(int sk = 1); 

Set to 1 to skip whitespace after a token read, otherwise. 

TSubString strip ( StripType s = Trailing, char c = ' '); 
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substr 



substring 



to lower 



to_upper 



Strips away c characters from the beginning, end, or both (beginning and 
end) of string s, depending on StripType. 

string substr ( size_t pos ) const; 

Creates a string containing a copy of the characters from pos to the end of 
the target string. 

string substr ( size_t pos, size_t n ) const; 

Creates a string containing a copy of not more than n characters from pos to 
the end of the target string. 

TSubString substring ( const char *cp ) 

Creates a TSubString object containing a copy of the characters pointed to 
by *cp. 

const TSubString substring ( const char *cp ) const; 

Creates a TSubString object containing a copy of the characters pointed to 
by *cp. 

TSubString substring ( const char *cp, size_t start ) 

Creates a TSubString object containing a copy of the characters pointed to 
by *cp, starting at character start. 

const TSubString substring ( const char *cp, size_t start ) const; 

Creates a TSubString object containing a copy of the characters pointed to 
by *cp, starting at character start. 

void to_lower() ; 

Changes the string to lowercase. 

void to_upper ( ) ; 

Changes target string to uppercase. 



Protected member functions 



assert element 



assert index 



cow 



void assert_element ( size_t pos ) const; 

Throws an outofrange exception if an invalid element is given. 

void assert_index( size_t pos ) const; 

Throws an outofrange exception if an invalid index is given. 

void cow() ; 
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Copy on write. Multiple instances of a string can refer to the same piece of 
data as long as it is in a read-only situation. If a string writes to the data, 
then cow (copy on write) is called to make a copy if more than one string is 
referring to it. 

valld_element i n t valid_element( size_t pos ) const; 

Returns 1 if pos is an element of the string, otherwise. 
valldjndex j_ n t valid_index( size_t pos ) const; 

Returns 1 if pos is a valid index of the string, otherwise. 



Operators 



Operator = 



Operator += 



Operator + 
Operator [] 



Operator () 



string & operator= (const string &s); 

If the target string is the same object as the parameter passed to the 
assignment, the assignment operator does nothing. Otherwise it performs 
any actions necessary to free up resources allocated to the target string, 
then copies s into the target string. 

string & operator += (const string &s) 

Appends the contents of the string s to the target string. 

string & operator += (const char *cp); 

Appends the contents of cp to the target string. 

friend string operator + (const string &s, const char *cp) ; 

Concatenates string s and cp. 

char & operator [] (size_t pos); 

Returns a reference to the character at position pos. 

char operator [] (size_t pos) const; 

Returns the character at position pos. 

char & operator () (size_t pos);. 

Returns a reference to the character at position pos. 

TSubString operator () (size_t start, size_t len); 

Returns the substring beginning at location start and spanning len bytes. 

TSubString operator () (const TRegexp & re); 

Returns the first occurrence of a substring matching regular expression re. 
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Operator == 



Operator != 



TSubString operator () (const TRegexp & re, size_t start); 

Returns the first occurrence of a substring matching regular expression re, 
beginning at location start. 

char operator () (size_t pos) const; 

Returns the character at position pos. 

const TSubString operator () (size_t start, size_t len) const; 

Returns the substring beginning at location start and spanning len bytes. 

const TSubString operator () (const TRegexp & pat) const; 

Returns the first occurrence of a substring matching regular expression re. 

const TSubString operator () (const TRegexp & pat, size_t start) const; 

Returns the first occurrence of a substring matching regular expression re, 
beginning at location start. 

friend int operator == ( const string &sl, const string &s2 ); 

Tests for equality of string si and string s2. Two strings are equal if they 
have the same length, and if the same location in each string contains 
characters that compare equally. Operator == returns a 1 to indicate that the 
strings are equal, and a to indicate that they are not equal. 

friend int operator == ( const string &sl, const char *cp ); 
friend int operator == ( const char *cp, const string &s ) ; 

Tests for equality of string si and char *cp. The two are equal if they have 
the same length, and if the same location in each string contains characters 
that compare equally. Operator == returns a 1 to indicate that the strings 
are equal, and a to indicate that they are not equal. 

friend int operator != ( const string &sl, const string &s2 ); 

Tests for inequality of strings si and s2. Two strings are equal if they have 
the same length, and if the same location in each string contains characters 
that compare equally. Operator != returns a 1 to indicate that the strings are 
not equal, and a to indicate that they are equal. 



friend int operator 
friend int operator 



const string &s, const char *cp ); 
const char *cp, const string &s 



Operator < 



Tests for inequality between string s and char *cp. The two are equal if they 
Have the same length, and if the same location in each string contains the 
same character. Operator != returns a 1 to indicate that the strings are not 
equal, and a to indicate that they are equal. 

friend int operator < ( const string &sl, const string &s2 ); 
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Compares string si to string s2. Returns 1 if string si is less than s2, 
otherwise. 

friend int operator < ( const string &s, const char *cp ); 
friend int operator < ( const char *cp, const string &s ) ; 

Compares string si to *cp2. Returns 1 if the left side of the expression is less 
than the right side, otherwise. 

Operator <= friend int operator <= ( const string &sl, const string &s2 ); 

Compares string si to string s2. Returns 1 if string si is less than or equal to 
s2, otherwise. 

friend int operator <= ( const string &s, const char *cp ); 
friend int operator <= ( const char *cp, const string &s ); 

Compares string si to *cp. Returns 1 if the left side of the expression is less 
than or equal to the right side, otherwise. 

Operator > friend int operator > ( const string &sl, const string &s2 ); 

Compares string si to string s2. Returns 1 if string si is greater than s2, 
otherwise. 

friend int operator > ( const string &s, const char *cp ); 
friend int operator > ( const char *cp, const string &s ) ; 

Compares string si to *cp2. Returns 1 if the left side of the expression is 
greater than the right side, otherwise. 

Operator >= friend int operator >= ( const string &sl, const string _FR &s2 ); 

Compares string si to string s2. Returns 1 if string si is greater than or 
equal to s2, otherwise. 

friend int operator >= ( const string &s, const char *cp ); 
friend int operator >= ( const char *cp, const string &s ) ; 

Compares string si to *cp. Returns 1 if the left side of the expression is 
greater than or equal to the right side, otherwise. 

Operator » friend ipstream & operator » ( ipstream & is, string & str ); 

Extracts string str from input stream is. 



Related global operators and functions 



Operator » istream & operator » (istream &is, string &s); 

Behaves the same as operator » (istream&, char *) (see Chapter 4), and 
returns a reference to is. 
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Operator « 



Operator + 



getline 



to lower 



to_upper 



ostream & operator « (ostream &os, const string & s); 

Behaves the same as operator « (ostreamk, const char *) (see Chapter 4) 
except that it does not terminate when it encounters a null character in the 
string. Returns a reference to os. 

opstream & operator « ( opstream & os, const string & str ); 

Inserts string str into persistent output stream os. 

string operator + ( const char *cp, const string & s); 

Concatenates *cp and string s. 

string operator + ( const string &sl, const string &s2 ); 
Concatenates string si and s2. 

istream & getline ( istream &is, string &s ) ; 

Behaves the same as istream: : getline (chptr, NPOS) , except that instead of 
storing into a char array, it stores into a string, getline returns a reference to 

is. 

istream & getline ( istream &is, string &s, char c ); 

Behaves the same as istream: :getline(cb, NPOS, c), except that instead of 
storing into a char array, it stores into a string, getline returns a reference to 
is. 

string to_lower( const string &s); 

Changes string s to lowercase. 

string to_upper (const string &s) ; 

Changes string s to uppercase. 



TSubString class 



cstring.h 



class TSubString 

Addresses selected substrings. 

Public member functions 



get_at 



char get_at( size_t pos ) const; 
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isjiull 
length 
put_at 

start 

tojower 

to_upper 



assert element 



Returns the character at the specified position. If pos > length ( ) -1, an 
exception is thrown. 

See also: put_at 

int is_null() const; 

Returns 1 if the string is empty, otherwise. 

size_t length () const; 
Returns the substring length. 

void put_at( size_t pos, char c ) 

Replaces the character at pos with c. If pos == length ( ) , putAt appends c to 
the target string. If pos > length ( ) , an exception is thrown. 

int start () const; 

Returns the index of the starting character. 

void tojower ( ) ; 

Changes the substring to lowercase. 

void to_upper() ; 

Changes the substring to uppercase. 

Protected member functions 

int assert_element (size_t pos) const; 

Returns 1 if pos represents a valid index into the substring, otherwise. 



Operator = 
Operator == 



Operators 



TSubString & operator = (const string &s) 
Copies s into the target substring. 



int operator 



(const char * cp) const; 



Tests for equality between the target substring and *cp. The two are equal if 
they have the same length, and if the same location in each string contains 
the same character. Operator == returns a 1 to indicate that the strings are 
equal, and a to indicate that they are not equal. 

int operator -- (const string & s) const; 
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Operator != 



Operator () 



Operator [] 



Operator 



Tests for equality between the target substring and string s. Two are equal 
if they have the same length, and if the same location in each string 
contains the same character. Operator == returns a 1 to indicate that the 
strings are equal, and a to indicate that they are not equal. 

int operator != (const char * cp) const; 

Tests for inequality between the target string and *cp. Two strings are equal 
if they have the same length, and if the same location in each string 
contains the same character. Operator != returns a 1 to indicate that the 
strings are not equal, and a to indicate that they are equal. 

int operator != (const string & s) const; 

Tests for inequality between the target string and string s. Two strings are 
equal if they have the same length, and if the same location in each string 
contains the same character. Operator != returns a 1 to indicate that the 
strings are not equal, and a to indicate that they are equal. 

char & operator () (size_t pos); 

Returns a reference to the character at position pos. 

char operator () (size_t pos) const; 

Returns the character at position pos. 

char & operator [] (size_t pos); 

Returns a reference to the character at position pos. 

char operator [] (size_t pos) const; 

Returns the character at position pos. 

int operator !() const; 

Detects null substrings. Returns 1 if the substring is not null. 



TCriticalSection class 



thread.h 



class TCriticalSection 

TCriticalSection provides a system-independent interface to critical sections 
in threads. TCriticalSection objects can be used in conjunction with 
TCriticalSection::Lock objects to guarantee that only one thread can be 
executing any of the code sections protected by the lock at any given time. 

See also: TCriticalSectionr.Lock 
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Constructor TCriticalSection ( ) ; 

Constructs a TCriticalSection object. 
Destructor -TCriticalSection ( ) ; 

Destroys a TCriticalSection object. 



TCriticalSection class 



TCriticalSection::Lock class 



thread.h 



class Lock 

This nested class handles locking and unlocking critical sections. Here's an 
example: 

TCriticalSection LockF; 

void f() 

{ 

TCriticalSection: :Lock(LockF) ; 

// critical processing here 
} 

Only one thread of execution will be allowed to execute the critical code 
inside function/ at any one time. 

Public constructors and destructor 



Constructor 



Destructor 



Lock( const TCriticalSectionk ); 

Requests a lock on the TCriticalSection object. If no Lock object in another 
thread holds a lock on that TCriticalSection object, the lock is allowed and 
execution continues. If a Lock object in another thread holds a lock on that 
object, the requesting thread is blocked until the lock is released. 

-Lock ( ) ; 

Releases the lock. 



TMutex class 



thread.h 



TMutex provides a system-independent interface to critical sections in 
threads. TMutex objects can be used in conjunction with TMutex: :Lock 
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objects to guarantee that only one thread can be executing any of the code 
sections protected by the lock at any given time. 

The differences between the classes TCriticalSection and TMutex are that a 
timeout can be specified when creating a Lock on a TMutex object, and that 
a TMutex object has an HMTX handle that can be used outside the class. 
This mirrors the distinction made in Windows NT between a 
CRITICALSECTION and a Mutex. Under NT a TCriticalSection object is 
much faster than a TMutex object. Under operating systems that don't make 
this distinction a TCriticalSection object can use the same underlying 
implementation as a TMutex, losing the speed advantage that it has under 
NT. 

Public constructors and destructor 



Constructor 



Destructor 



TMutexO; 

Constructs a TMutex object. 

-TMutex ( ) ; 

Destroys a TMutex object. 



Operators 



HMTX 



operator HMTXO const; 

Returns a handle to the underlying TMutex object, for use in operating 
system calls that require it. 



TMutex::Lock class 



thread.h 



This nested class handles locking and unlocking TMutex objects. 

Public constructors 

Constructor Lock( const TMutexk, unsigned long timeOut = NoLimit ); 

Requests a lock on the TMutex object. If no Lock object in another thread 
holds a lock on that TMutex object, the lock is allowed and execution 
continues. If a Lock object in another thread holds a lock on that object, the 
requesting thread is blocked until the lock is released. 
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Public member functions 



Release 



void Released ; 

Releases the lock on the TMutex object. 



TSync class 



thread.h 



TSync provides a system-independent interface for building classes that act 
like monitors — classes in which only one member function can execute on a 
particular instance at any one time. TSync uses TCriticalSection, has no 
public members, and can only be used as a base class. Here is an example 
of TSync in use: 

class ThreadSafe : private TSync 

{ 

public: 

void f ( ) ; 

void g ( ) ; 
private: 

int i; 
}; 

void ThreadSafe: :f() 



Lock (this) ; 
if( i == 2 : 
i = 3; 



void ThreadSafe: :g() 
{ 

Lock (this) ; 

if( i == 3 ) 
i = 2; 
} 

See also: class TSyncr.Lock 



Protected constructors 



Constructor 



Constructor 



TSync ( ) ; 

Default constructor. 

TSync ( const TSynck 
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Copy constructor. Does not copy the TCriticalSection object. 

Protected operators 

Operators cons t TSync& operator = ( const TSync& s ) 

Assigns s to the target, and does not copy the TCriticalSection object. 

TSync::Lock class thread.h 

class Lock : private TCriticalSection: :Lock 

This nested class handles locking and unlocking critical sections. 

Public constructors and destructor 

Constructor L ock( const TSync *s ); 

Requests a lock on the critical section of the TSync object pointed to by s. If 
no other Lock object holds a lock on that TCriticalSection object, the lock is 
allowed and execution continues. If another Lock object holds a lock on that 
object, the requesting thread is blocked until the lock is released. 

Destructor ~Lock(); 

Releases the lock. 

TThread class thread.h 

class TThread 

TThread provides a system-independent interface to threads. Here is an 
example: 

class TimerThread : private TThread 

{ 

public: 

TimerThread ( ) : Count (0) {} 
private: 

unsigned long Run(); 

int Count; 
}; 

unsigned long TimerThread: : Run () 
{ 
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// loop 10 times 

while ( Count++ < 10 ) 

{ 

Sleep(lOOO); // delay 1 second 
cout « "Iteration " « Count « endl; 

} 

return 0L; 
} 

int main() 
{ 

TimerThread timer; 

timer.StartO ; 

Sleep( 20000 ); // delay 20 seconds 



return 0; 
} 

Type definitions 



Status enum status { Created, Running, Suspended, Finished, Invalid }; 

Describes the state of the thread, as follows: 

a Created. The object has been created but its thread has not been started. 
The only valid transition from this state is to Running, which happens on 
a call to Start. In particular, a call to Suspend or Resume when the object is 
in this state is an error and will throw an exception. 

m Running. The thread has been started successfully. There are two 
transitions from this state: 

o When the user calls Suspend, the object moves into the Suspended state, 
e When the thread exits, the object moves into the Finished state. 

Calling Resume on an object that is in the Running state is an error and 
will throw an exception. 

a Suspended. The thread has been suspended by the user. Subsequent calls 
to Suspend nest, so there must be as many calls to Resume as there were to 
Suspend before the thread resumes execution. 

■ Finished. The thread has finished executing. There are no valid transitions 
out of this state. This is the only state from which it is legal to invoke the 
destructor for the object. Invoking the destructor when the object is in 
any other state is an error and will throw an exception. 
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Protected constructors and destructor 



Constructor 



Constructor 



Destructor 



GetPriority 

GetStatus 

Resume 
SetPriority 

Start 

Suspend 

Terminate 

TerminateAndWait 



TThread ( ) ; 

Constructs an object of type TThread. 

TThread ( const TThreadk ) ; 

Copy constructor. Puts the target object into the Created state. 

virtual -TThread () ; 

Destroys the TThread object. 



Public member functions 



int GetPriority () const; 
Gets the thread priority. 
See also: SetPriority 

Status GetStatus () const; 

Returns the current status of the thread. See data member Status for 
possible values. 

unsigned long Resumed; 

Resumes execution of a suspended thread. 

int SetPriority ( int ) ; 

Sets the thread priority. 

See also: GetPriority 

THANDLE Start () ; 

Begins execution of the thread, and returns the thread handle. 

unsigned long SuspendO; 

Suspends execution of the thread. 

void Terminate ( ) ; 

Sets an internal flag that indicates that the thread should exit. The derived 
class can check the state of this flag by calling ShouldTerminate. 

void TerminateAndWait ( unsigned long timeout = NoLimit ) ; 

Combines the behavior of Terminate and WaitForExit. Sets an internal flag 
that indicates that the thread should exit and blocks the calling thread until 
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the internal thread exits or until the time specified by timeout, in 
milliseconds, expires. A timeout of -1 says to wait indefinitely. 

WaitForExit vo id WaitForExit ( unsigned long timeout = NoLimit ); 

Blocks the calling thread until the internal thread exits or until the time 
specified by timeout, in milliseconds, expires. A timeout of -1 says wait 
indefinitely. 



Protected member functions 

ShOUldTerminate i n t ShouldTerminate ( ) const; 



Returns a nonzero value to indicate that Terminate or TerminateAndWait has 
been called and that the thread will finish its processing and exit. 

Protected operators 



Operator = 



const TThreadk operator 



const TThreadk 



The TThread assignment operator. The target object must be in either the 
Created or Finished state. If so, assignment puts the target object into the 
Created state. If the object is not in either state an exception will be thrown. 



TThread::TThreadError class 



thread.h 



class TThreadError 

TThreadError defines the exceptions thrown when a threading error occurs. 



ErrorType 



Type definitions 



enum ErrorType 
{ 

SuspendBeforeRun, 
ResumeBeforeRun, 
ResumeDuringRun, 
SuspendAf terExit , 
ResumeAfterExit, 
CreationFailure, 
DestroyBef oreExit , 
AssignError 
}; 
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Identifies the type of error that occurred. The following list explains each 
error type: 

■ SuspendBeforeRun. The user called Suspend on an object before calling 

Start. 

u ResumeBeforeRun. The user called Resume on an object before calling Start. 

u ResumeDuringRun. The user called Resume on a thread that was not 
suspended. 

b SuspendAfterExit. The user called Suspend on an object whose thread had 
already exited. 

■ Resume AfterExit. The user called Resume on an object whose thread had 
already exited. 

■ CreationFailure. The operating system was unable to create the thread. 

■ DestroyBeforeExit. The object's destructor was invoked before its thread 
had exited. 

■ AssignError. An attempt was made to assign to an object that was not in 
either the Created or Finished state. 

Public member functions 

GetErrorType ErrorType GetErrorType!) const; 

Returns the ErrorType for the error that occurred. 

TTime type definitions time.h 

typedef unsigned HourTy; 
typedef unsigned MinuteTy; 
typedef unsigned SecondTy; 
typedef unsigned long ClockTy; 

Type definitions for hours, minutes, seconds, and seconds since January 1, 
1901. 



TTime class time.h 

class TTime 

Class TTime encapsulates time functions and characteristics. 
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Public constructors 



Constructor 



Constructor 



Constructor 



Constructor 



AsString 
BeginDST 
Between 
CompareTo 

EndDST 

Hash 

Hour 

HourGMT 

IsDST 



TTime ( ) ; 

Constructs a TTime object with the current time. 

TTime ( ClockTy s ) ; 

Constructs a TTime object with the given s (seconds since January 1, 1901). 

TTime ( HourTy h, MinuteTy m, Secondly s = ); 
Constructs a TTime object with the given time and today's date. 
TTime( const TDate&, HourTy h=0, MinuteTy m=0, SecondTy s=0 ); 
Constructs a TTime object with the given time and date. 



Public member functions 



string AsString () const; 

Returns a string object containing the time. 

static TTime BeginDST ( unsigned year ); 

Returns the start of daylight savings time for the given year. 

int Between ( const TTimek a ; const TTimek b ) const; 

Returns 1 if the target date is between TTimes a and b, otherwise. 

int CompareTo ( const TTime & ) const; 

Compares t to this TTime object and returns if the times are equal, 1 if Ms 
earlier, and -1 if t is later. 

static TTime EndDST ( unsigned year ); 

Returns the time when daylight savings time ends for the given year. 

unsigned Hash() const; 

Returns seconds since January 1, 1901. 

HourTy Hour() const; 

Returns the hour in local time. 

HourTy HourGMT () const; 

Returns the hour in Greenwich Mean Time. 

int IsDST () const; 
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IsValid 



Max 



Min 



Minute 



MinuteGMT 



PrlntDate 



Second 



Seconds 



Returns 1 if the time is in daylight savings time, otherwise. 

int IsValid () const; 

Returns 1 if this TTime object contains a valid time, otherwise. 

TTime Max( const TTimek t ) const; 

Returns either this TTime object or t, whichever is greater. 

TTime Min( const TTime& t ) const; 

Returns either this TTime object or t, whichever is lesser. 

MinuteTy Minute () const; 

Returns the minute in local time. 

MinuteTy MinuteGMT () const; 

Returns the minute in Greenwich Mean Time. 

static int PrintDate( int flag); 

Set flag to 1 to print the date along with the time; set to to not print the 
date. Returns the old setting. 

SecondTy Second () const; 

Returns seconds. 

ClockTy Seconds!) const; 

Returns seconds since January 1, 1901. 



Protected member functions 



AssertDate 



static int AssertDate ( const TDate& d ); 

Returns 1 if d is between the earliest valid date (RefDate) and the latest valid 
date (MaxDate). 



Protected data members 



RefDate 



MaxDate 



static const TDate RefDate; 

The minimum valid date for TTime objects: January 1, 1901. 

static const TDate MaxDate; 

The maximum valid date for TTime objects. 
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Operators 

Operator < i n t operator < ( const TTime& t ) const; 

Returns 1 if the target time is less than time t, otherwise. 
Operator <= i n t operator <= ( const TTimek t ) const; 

Returns 1 if the target time is less than or equal to time t, otherwise. 
Operator > int operator > ( const TTimek t ) const; 

Returns 1 if the target time is greater than time t, otherwise. 
Operator >= { n i operator >= ( const TTimek t ) const; 

Returns 1 if the target time is greater than or equal to time t, otherwise. 
Operator == i n t operator == ( const TTimek t ) const; 

Returns 1 if the target time is equal to time t, otherwise. 
Operators j_ n t operator != ( const TTime& t ) const; 

Returns 1 if the target time is not equal to time t, otherwise. 
Operator ++ vo id operator ++ ( ) ; 

Increments time by 1 second. 
Operator — vo i(j operator -- (); 

Decrements time by 1 second. 
Operator += vo j_ci operator += (long s) ; 

Adds s seconds to the time. 
Operator -= vo id operator -= (long s); 

Subtracts s seconds from the time. 

Operator + friend TTime operator + ( const TTime& t, long s ); 

friend TTime operator + ( long s, const TTime& t ); 

Adds s seconds to time t . 

Operator- friend TTime operator - ( const TTime& t, long s ); 

friend TTime operator - ( long s, const TTimek t ); 

Performs subtraction, in seconds, between s and t . 

Operator « friend ostreamk operator « ( ostreamk os, const TTime& t) ; 

Inserts time t into output stream os. 
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TTime class 



friend opstreamk operator « ( opstreamk s,' const TTimek d 
Inserts time t into persistent stream s. 
Operator » friend ipstream& operator » ( ipstreamk s, TTimek d ); 

Extracts time t from persistent stream s. 



466 Borland C++ for OS/2 Library Reference 



A 



Run-time library cross-reference 



This appendix is an overview of the Borland C++ library routines and 
include files. 

This appendix 

■ Names the object libraries and other files found the LIB directory, and 
describe their uses. 

■ Explains why you might want to obtain the source code for the Borland 
C++ run-time library. 

b Lists and describes the header files. 

b Summarizes the different categories of tasks performed by the library 
routines. 

Borland C++ has several hundred functions and macros that you call from 
within your C and C++ programs to perform a wide variety of tasks, 
including low- and high-level I/O, string and file manipulation, memory 
allocation, process control, data conversion, mathematical calculations, and 
much more. These functions and macros, collectively referred to as library 
routines, are documented in Chapter 2 of this book. 



The run-time libraries 



The following table lists the OS/2 libraries names and uses. 
File name Use 

BPMCC.LIB Static-link implementation of the Borland Presentation Manager custom controls. 

BPMCC.DLL Dynamic-link implementation of the Borland Presentation Manager custom 
controls. 

C02.OBJ Startup code for EXE files (must be first .OBJ) 

C02D.OBJ Startup code for DLL files (must be first .OBJ) 

0S2.LIB Import library for OS/2 API 

C2.LIB Single-threaded static-link run-time library 
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C2MT.LIB 

C2.DLL 

C2I.LIB 

C2MT.DLL 
C2MTI.LIB 

FILEINFO.OBJ 

LOCALE.BLL 

OBSOLETE.LIB 

POPUP.OBJ 



ti-threaded static-link run-time library 

Single-threaded dynamic-link run-time library 

Import library for single-threaded dynamic-link run-time library. Link with this to 
use C2.DLL 



Multi-threaded dynamic-link run-time library 

Import library for multi-threaded dynamic-link run-time library. Link with this to 
use C2MT.DLL 

Link with this file to allow file handle information to be passed to child processes 
started with execl and spawn functions. 

Provides locale-specific data. 

Provides obsolete global variables 

Link with this file to cause runtime messages (such as those printed by the abort 
and assert functions) to be displayed in a pop-up character-mode screen. 

WILDARGS.OBJ Link with this file for automatic expansion of wildcard file names on the command 
line. 



For these examples you 

must provide your own 

file names in place of 

OBJS, EXE, and MAP. 



The following table lists the container libraries: 

BIDS2.LIB Static library 

BIDSDB2.LIB Static library, diagnostic version 

BIDS2I.UB Import static library 

BIDS402.DLL Dynamic link library 

BIDS40D2.DLL Dynamic link library, diagnostic version 

Here is an example of how you create an EXE that uses the single-threaded 
static run-time library: 

TLINK /TOE C02.OBJ <0BJS>, <EXE>, <MAP>, 0S2.LIB C2.LIB 

This example creates an EXE that uses the dynamic link library C2.DLL: 

TLINK /TOE C02.OBJ <0BJS>, <EXE>, <MAP>, 0S2.LIB C2I.LIB 

This example creates a DLL that uses the multi-threaded static run-time 
library: 

TLINK /TOE C02D.OBJ <0BJS>, <EXE>, <MAP>, 0S2.LIB C2MT.LIB 

See also the Programmer's Guide, Chapter 9, for additional information and 
examples on how to use the various libraries. 
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Reasons to access the run-time library source code 

There are several good reasons why you might want to obtain the source 
code for the run-time library routines: 

■ You might find that a particular function you want to write is similar to, 
but not the same as, a Borland C++ function. With access to the run-time 
library source code, you could tailor the library function to your own 
needs, and avoid having to write a separate function of your own. 

■ Sometimes, when you are debugging code, you might want to know 
more about the internals of a library function. Having the source code to 
the run-time library would be of great help in this situation. 

b You might want to delete the leading underscores on C symbols. Access 
to the run-time library source code will let you delete them. 

n You can learn a lot from studying tight, professionally written library 
source code. 

For all these reasons, and more, you will want to have access to the Borland 
C++ run-time library source code. Because Borland believes strongly in the 
concept of "open architecture," we have made the Borland C++ run-time 
library source code available for licensing. All you have to do is fill out the 
order form distributed with your Borland C++ package, include your 
payment, and we'll ship you the Borland C++ run-time library source code. 

The Borland C++ header files 



C++ header files, and 

header files defined 

by ANSI C, are 

marked in the margin. 



Header files, also called include files, provide function prototype 
declarations for library functions. Data types and symbolic constants used 
with the library functions are also defined in them, along with global 
variables defined by Borland C++ and by the library functions. The Borland 
C++ library follows the ANSI C standard on names of header files and their 
contents. 



alloc.h 

ANSI C assert.h 
O0j> bcd.h 



S+fe checks - h 



Declares memory management functions (allocation, 
deallocation, and so on). 

Defines the assert debugging macro. 

Declares the C++ class bed and the overloaded operators 
for bed and bed math functions. 

Defines PRECONDITION, WARN, and TRACE diagnostic 
macros. 
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(g£+fc> complex.h 
conio.h 



Q+j+> constrea.h 



Q$p cstring.h 
ANSI C ctype.h 

dir.h 

direct.h 

dirent.h 

dos.h 

ANSI C errno.h 
©$+> excepts 

excpt.h 

fcntl.h 

ANSI C float.h 
(S£fr> fstream.h 



(g+J£> generich 
io.h 



(g>fe iomanip.h 
(&+fc? iostream.h 



Declares the C++ complex math functions. 

Declares various functions used in calling the operating 
system console I/O routines. The functions defined in this 
header file cannot be used in PM applications. 

Declares C++ classes and methods to support console 
output. 

Declares the ANSI C++ string class support. 

Contains information used by the character classification 
and character conversion macros (such as isalpha and 
toascii). 

Contains structures, macros, and functions for working 
with directories and path names. 

Defines structures, macros, and functions for dealing with 
directories and path names. 

Declares functions and structures for POSIX directory 
operations. 

Defines various constants and gives declarations needed 
for DOS and 8086-specific calls. 

Defines constant mnemonics for the error codes. 

Declares routines that provide support for ANSI C++ 
exceptions. 

Declares routines and keywords that provide support for 
C-based structured exceptions. 

Defines symbolic constants used in connection with the 
library routine open. 

Contains parameters for floating-point routines. 

Declares the C++ stream classes that support file input and 
output. 

Contains macros for generic class declarations. 

Contains structures and declarations for low-level 
input/output routines. 

Declares the C++ streams I/O manipulators and contains 
templates for creating parameterized manipulators. 

Declares the basic C++ streams (I/O) routines. 
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ANSIC 


limits.h 


ANSIC 


locale.h 




sysMocking.h 




malloc.h 


ANSIC 


math.h 



mem.h 





memory .h 


$J> 


new.h 




process .h 




search.h 


ANSIC 


setjmp.h 




share.h 


ANSIC 


signal.h 


ANSIC 


stdarg.h 


ANSIC 


stddef.h 


ANSIC 


stdio.h 



stdiostr.h 



Contains environmental parameters, information about 
compile-time limitations, and ranges of integral quantities. 

Declares functions that provide country- and language- 
specific information. 

Definitions for mode parameter of locking function. 

Memory management functions and variables. 

Declares prototypes for the math functions and math error 
handlers. 

Declares the memory-manipulation functions. (Many of 
these are also defined in string.h.) 

Memory manipulation functions. 

Access to _new_handler and _set_new_handler. 

Contains structures and declarations for the spawn. . . and 
exec... functions. 

Declares functions for searching and sorting. 

Defines a type jmpjbuf used by the longjmp and setjmp 
functions and declares the functions longjmp and setjmp. 

Defines parameters used in functions that make use of file- 
sharing. 

Defines constants and declarations for use by the signal and 
raise functions. 

Defines macros used for reading the argument list in 
functions declared to accept a variable number of argu- 
ments (such as vprintf, vscanf, and so on). 

Defines several common data types and macros. 

Defines types and macros needed for the standard I/O 
package defined in Kernighan and Ritchie and extended 
under UNIX System V. Defines the standard I/O pre- 
defined streams stdin, stdout, and stderr, and declares 
stream-level I/O routines. 

Declares the C++ (version 2.0) stream classes for use with 
stdio FILE structures. You should use iostream.h for new 
code. 
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ANSI C stdlib.h 

ANSI C string.h 

(&£]+> strstrea.h 

sys\stat.h 

ANSIC time.h 



sys\timeb.h 

sys\types.h 
(g£(^ typeinfo.h 

utime.h 

values.h 

varargs.h 



Declares several commonly used routines: conversion 
routines, search/sort routines, and other miscellany. 

Declares several string-manipulation and memory- 
manipulation routines. 

Declares the C++ stream classes for use with byte arrays in 
memory. 

Defines symbolic constants used for opening and creating 
files. 

Defines a structure filled in by the time-conversion routines 
asctime, localtime, and gmtime, and a type used by the 
routines dime, difftime, gmtime, localtime, and stime; also 
provides prototypes for these routines. 

Declares the function ftime and the structure timeb that ftime 
returns. 

Declares the type timej used with time functions. 

Provides declarations for ANSI C++ run-time type 
identification (RTTI). 

Declares the utime function and the utimbuf struct that it 
returns. 

Defines important constants, including machine depen- 
dencies; provided for UNIX System V compatibility. 

Definitions for accessing parameters in functions that 
accept a variable number of arguments. Provided for UNIX 
compatibility; you should use stdarg.h for new code. 



Library routines by category 



The Borland C++ library routines perform a variety of tasks. In this section, 
we list the routines, along with the include files in which they are declared, 
under several general categories of task performed. Chapter 2 contains 
complete information about the functions. 



C++ prototyped 
routines 



Certain routines described in this book have multiple declarations. You 
must choose the prototype appropriate for your program. In general, the 
multiple prototypes are required to support the original C implementation 
and the stricter and sometimes different C++ function declaration syntax. 
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For example, some string-handling routines have multiple prototypes 
because in addition to the ANSI-C specified prototype, Borland C++ 
provides prototypes that are consistent with the ANSI C++ draft. 

getvect (dos.h) strchr (string.h) 

max (stdlib.h) strpbrk (string.h) 

memchr (string.h) strrchr (string.h) 

min (stdlib.h) strstr (string.h) 

setvect (dos.h) 



Classification 
routines 



These routines classify ASCII characters as letters, control characters, 
punctuation, uppercase, and so on. 



isalnum 

isalpha 

isascii 

iscntrl 

isdigit 

isgraph 



(ctype.h) 
(ctype.h) 
(ctype.h) 
(ctype.h) 
(ctype.h) 
(ctype.h) 



islower 
isprint 
ispunct 
isspace 
isupper 
isxdigit 



(ctype.h) 
(ctype.h) 
(ctype.h) 
(ctype.h) 
(ctype.h) 
(ctype.h) 



Conversion 
routines 



These routines convert characters and strings from alpha to different 

numeric representations (floating-point, integers, longs) and vice versa, and 

from uppercase to lowercase and vice versa. 

atof (stdlib.h) strtol (stdlib.h) 

atoi (stdlib.h) _strtold (stdlib.h) 

atol (stdlib.h) strtoul (stdlib.h) 

ecvt (stdlib.h) toascii (ctype.h) 

fcvt (stdlib.h) Jolower (ctype.h) 

govt (stdlib.h) tolower (ctype.h) 

itoa (stdlib.h) Joupper (ctype.h) 

Itoa (stdlib.h) toupper (ctype.h) 

strtod (stdlib.h) ultoa (stdlib.h) 



Directory control 


These routines 


manipulate directories and path names 




routines 












chdir 


(dir.h) 


fnmerge 


(dir.h) 




_chdrive 


(direct.h) 


fnsplit 


(dir.h) 




closedir 


(dirent.h) 


Jullpath 


(stdlib.h) 




_dosJindfirst 


(dos.h) 


getcurdir 


(dir.h) 




_dos_findnext 


(dos.h) 


getcwd 


(dir.h) 




_dos_getdiskfree 


(dos.h) 


_getdcwd 


(direct.h) 




_dos_getdrive 


(dos.h) 


getdisk 


(dir.h) 




_dos_setdrive 


(dos.h) 


_getdrive 


(direct.h) 




findfirst 


(dir.h) 


jnakepath 


(stdlib.h) 




findnext 


(dir.h) 


mkdir 


(dir.h) 
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tnktemp 

opendir 

readdir 

rewinddir 

rmdir 



(dir.h) 

(dirent.h) 

(dirent.h) 

(dirent.h) 

(dir.h) 



_searchenv 


(stdlib.h) 


searchpath 


(dir.h) 


searchstr 


(stdlib.h) 


setdisk 


(dir.h) 


_splitpath 


(stdlib.h) 



Diagnostic 
routines 



These routines provide built-in troubleshooting capability. 



assert 
CHECK 
jnatherr 
matherrl 



(assert.h) 
(checks.h) 
(math.h) 
(math.h) 



perror (errno.h) 

PRECONDITION (checks.h) 
TRACE (checks.h) 

WARN (checks.h) 



Inline routines 



Inputbutput 
routines 



These routines have inline versions. The compiler will generate code for the 
inline versions when you use #pragma intrinsic or if you specify program 
optimization. See the User's Guide, Appendix A, "The optimizer," for more 
details. 



abs 
alloca 
_crotl 
_crotr 
Jrotl 
Jrotr 
memchr 
memcmp 
memcpy 
memset 
_rotl 
rotr 



(math.h) 

(malloc.h) 

(stdlib.h) 

(stdlib.h) 

(stdlib.h) 

(stdlib.h) 

(mem.h) 

(mem.h) 

(mem.h) 

(mem.h) 

(stdlib.h) 

(stdlib.h) 



stpcpy 

strcat 

strchr 

strcmp 

strcpy 

strlen 

strncat 

strncmp 

strncpy 

strnset 

strrchr 

strset 



(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 



These routines provide stream- and operating-system level I/O capability. 



access 

_chmod 

chmod 

chsize 

clearerr 

_close 

close 

_creat 

creat 

creatnew 

creattemp 

cscanf 



(io.h) 

(io.h) 

(io.h) 

(io.h) 

(stdio.h) 

(io.h) 

(io.h) 

(io.h) 

(io.h) 

(io.h) 

(io.h) 

(conio.h) 



_dos_close 


(dos.h) 


_dos_creat 


(dos.h) 


_dos_creatnew 


(dos.h) 


_dos_getfileattr 


(dos.h) 


_dos_getftime 


(dos.h) 


_dos_open 


(dos.h) 


_dos_read 


(dos.h) 


_dos_setfileattr 


(dos.h) 


_dos_setftime 


(dos.h) 


_dos_write 


(dos.h) 


dup 


(io.h) 


dup2 


(io.h) 
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eof 

fclose 

fcloseall 

fdopen 

feof 

ferror 

fflush 

fgetc 

fgetchar 

fgetpos 

fgets 

filelength 

fileno 

flushall 

fopen 

fprintf 

fputc 

fputchar 

fputs 

fread 

freopen 

fscanf 

fseek 

fsetpos 

Jsopen 

fstat 

ftell 

Jlruncate 

fwrite 

getc 

getch 

getchar 

getche 

getftime 

gets 

getw 

isatty 

kbhit 

lock 

locking 

Iseek 

_open 

open 



(io.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(io.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(sys\stat.h) 

(stdio.h) 

(io.h) 

(stdio.h) 

(stdio.h) 

(conio.h) 

(stdio.h) 

(conio.h) 

(io.h) 

(stdio.h) 

(stdio.h) 

(io.h) 

(conio.h) 

(io.h) 

(io.h) 

(io.h) 

(io.h) 

(io.h) 



perror 


'stdio.h) 


_pipe 


(io.h) 


printf 


^stdio.h) 


putc 


stdio.h) 


put char 


stdio.h) 


puts 


stdio.h) 


putw 


(stdio.h) 


_read 


(io.h) 


read 


(io.h) 


remove 


'stdio.h) 


rename 


'stdio.h) 


rewind 


(stdio.h) 


rmtmp 


stdio.h) 


scanf 


stdio.h) 


setbuf 


stdio.h) 


_setcursortype 


(conio.h) 


setftime 


(io.h) 


setmode 


(io.h) 


setvbuf 


stdio.h) 


sopen 


(io.h) 


sprintf 


stdio.h) 


sscanf 


(stdio.h) 


stat 


sysXstat.h) 


_strerror 


string.h, stdio.h) 


strerror 


stdio.h) 


tell 


(io.h) 


tempnam 


'stdio.h) 


tmpfile 


stdio.h) 


tmpnam 


stdio.h) 


jtruncate 


(io.h) 


umask 


(io.h) 


ungetch 


conio.h) 


unlink 


(dos.h) 


unlock 


(io.h) 


utime 


utime.h) 


vfprintf 


stdio.h) 


vfscanf 


stdio.h) 


vprintf 


'stdio.h) 


vscanf 


'stdio.h) 


vsprintf 


stdio.h) 


vsscanf 


(io.h) 


jwrite 


(io.h) 
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Interface routines 



These routines provide operating system and machine-specific capabilities. 



country 
getdfree 
getverify 



(dos.h) 
(dos.h) 
(dos.h) 



setverify 
sleep 



(dos.h) 
(dos.h) 



International 
locale API 
routines 



These routines are affected by the current locale. The current locale is 
specified by the setlocale function and is enabled by defining 

USELOCALES with -D command line option. When you define 

USELOCALES , only function versions of the following routines are 

used in the run-time library rather than macros. See online Help for a 
discussion of the International API. 



cprintf 

cscanf 

fprintf 

fscanf 

isalnum 

isalpha 

iscntrl 

isdigit 

isgraph 

{slower 

isprint 

ispunct 

isspace 

isupper 

isxdigit 

localeconv 

printf 



(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(ctype.h) 

(ctype.h) 

(ctype.h) 

(ctype.h) 

(ctype.h) 

(ctype.h) 

(ctype.h) 

(ctype.h) 

(ctype.h) 

(ctype.h) 

(ctype.h) 

(locale.h) 

(stdio.h) 



scanf 

setlocale 

sprintf 

sscanf 

strcoll 

strftime 

strlwr 

strupr 

strxfrm 

tolower 

toupper 

vfprintf 

vfscanf 

vprintf 

vscanf 

vsprintf 

vsscanf 



(stdio.h) 

(locale.h) 

(stdio.h) 

(stdio.h) 

(string.h) 

(time.h) 

(string.h) 

(string.h) 

(string.h) 

(ctype.h) 

(ctype.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 



Manipulation 
routines 



These routines handle strings and blocks of memory: copying, comparing, 
converting, and searching. 



mblen (stdlib.h) strchr 

mbstowcs (stdlib.h) strcmp 

mbtowc (stdlib.h) strcoll 

memccpy (mem.h, string.h) strcpy 

memchr (mem.h, string.h) strcspn 

memcmp (mem.h, string.h) strdup 

memcpy (mem.h, string.h) strerror 

memicmp (mem.h, string.h) stricmp 

memmove (mem.h, string.h) strcmpi 

memset (mem.h, string.h) strlen 

stpcpy (string.h) strlwr 

strcat (string.h) strncat 



(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
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strncmp 


(string.h) 


strset 


(string.h) 




strncmpi 


(string.h) 


strspn 


(string.h) 




strncpy 


(string.h) 


strstr 


(string.h) 




strnicmp 


(string.h) 


strtok 


(string.h) 




strnset 


(string.h) 


strupr 


(string.h) 




strpbrk 


(string.h) 


strxfrm 


(string.h) 




strrchr 


(string.h) 


westombs 


(stdlib.h) 




strrev (string.h) wctomb 
These routines perform mathematical calculation 


(stdlib.h) 


Math routines 


s and conversions. 




abs 


[complex.h, stdlib.h) 


cosh 


(complex.h, math.h) 




acos 


[complex.h, math.h) 


coshl 


(math.h) 




acosl 


[math.h) 


cosl 


(math.h) 




arg 


[complex.h) 


div 


(math.h) 




asin 


(complex.h, math.h) 


ecvt 


(stdlib.h) 




asinl 


(math.h) 


exp 


(complex.h, math.h) 




atari 


(complex.h, math.h) 


expl 


(math.h) 




atanl 


(complex.h, math.h) 


fobs 


(math.h) 




atanll 


[math.h) 


fabsl 


(math.h) 




atanl 


(math.h) 


fevt 


(stdlib.h) 




atof 


(stdlib.h, math.h) 


floor 


(math.h) 




atoi 


(stdlib.h) 


floorl 


(math.h) 




atol 


(stdlib.h) 


fmod 


(math.h) 




_atold 


(math.h) 


fmodl 


(math.h) 




bed 


(bcd.h) 


Jpreset 


(float.h) 




cabs 


[math.h) 


frexp 


(math.h) 




cabsl 


(mathh) 


frexpl 


(math.h) 




ceil 


(math.h) 


gcvt 


(stdlib.h) 




ceill 


(math.h) 


hypot 


(math.h) 




_clear87 


(float.h) 


hypotl 


(math.h) 




complex 


[complex.h) 


imag 


(complex.h) 




con] 


[complex.h) 


itoa 


(stdlib.h) 




_control87 


(float.h) 


labs 


(stdlib.h) 




cos 


[complex.h, math.h) 


Idexp 


(math.h) 




Idexpl 


(math.h) 


modfl 


(math.h) 




Idiv 


(math.h) 


norm 


(complex.h) 




log 


(complex.h, math.h) 


polar 


(complex.h) 




logl 


(math.h) 


poly 


(math.h) 




loglO 


[complex.h, math.h) 


polyl 


(math.h) 




loglOl 


[math.h) 


pow 


(complex.h, math.h) 




Jrotl 


(stdlib.h) 


powlO 


(math.h) 




Jrotr 


(stdlib.h) 


powlOl 


(math.h) 




Itoa 


(stdlib.h) 


povol 


(math.h) 




jnatherr 


[math.h) 


rand 


(stdlib.h) 




jnatherrl 


[math.h) 


random 


(stdlib.h) 




modf 


[math.h) 


randomize 


(stdlib.h) 
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real (complex.h) 

_rotl (stdlib.h) 

_rotr (stdlib.h) 

sin (complex.h, math.h) 

sink (complex.h, math.h) 

sinhl (math.h) 

sinl (math.h) .h, math.h) 

sqrt (complex.h, math.h) 

sqrtl (math.h) 

srand (stdlib.h) 



_status87 


(float.h) 


strtod 


(stdlib.h) 


strtol 


(stdlib.h) 


_strtold 


(stdlib.h) 


strtoul 


(stdlib.h) 


tan 


(complex.h, math.h) 


tank 


(complex.h, math.h) 


tanhl 


(complex.h, math.h) 


tanl 


(math.h) 


ultoa 


(stdlib.h) 



Memory routines 


These routines 


provide dynamic 


memory allocation. 






alloca 


(malloc.h) 




Jieapmin 


(malloc.h) 




calloc 


(alloc.h, 




heapwalk 


(alloch) 






stdlib.h) 




Jieapwalk 


(malloc.h) 




free 


(alloc.h, 
stdlib.h) 




malloc 


(alloc.h, 
stdlib.h) 




Jieapadd 


(malloc.h) 




realloc 


(alloc.h, 




heapcheck 


(alloch) 






stdlib.h) 




heapcheckfree 


(alloch) 




_set_new_handler 


(new.h) 




heapchecknode 
These routines 


(alloch) 
provide nonlocal 


stackavail 
goto capabilities and ] 


(malloc.h) 


Miscellaneous 


iocale. 


routines 














localeconv 


(locale.h) 




setjmp 


(setjmp.h) 




longjmp 


(setjmp.h) 




setlocale 


(locale.h) 



Obsolete 
definitions 



The following global variables have been renamed to comply with ANSI 
naming requirements. You should always use the new names. If you link 
with libraries that were compiled with Borland C++ 3.1 (or earlier) header 
files, you will get the message 

Error: undefined external varname in module LIBNAME.LIB 

A library module that results in such an error should be recompiled. How- 
ever, if you cannot recompile the code for such libraries, you can link with 
OBSOLETE.LIB to resolve the external variable names. 

The following global variables have been renamed: 



Table A.1 

Obsolete global 

variables 



Old name 



New name 



Header file 



daylight 

directvideo 

environ 



_daylight 
_directvideo 
environ 



time.h 

conio.h 

stdlib.h 
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Table A.1 : Obsolete global variables (continued) 



sys_errlist 


_sys_errlist 


errno.h 


sys_nerr 


_sys_nerr 


errno.h 


timezone 


timezone 


time.h 


tzname 


tzname 


time.h 



The old names of the following functions are available. However, the 
compiler will generate a warning that you are using an obsolete name. 
Future versions of Borland C++ might not provide support for the old 
function names. 

The following function names have been changed: 



Table A.2 


Old name 


New name 


Header file 


Obsolete function 
names 








_chmod 


_rtl_chmod 


io.h 




_close 


_rtl_close 


io.h 




_creat 


_rtl_creat 


io.h 




_heapwalk 


_rtl_heapwalk 


malloc.h 




_open 


_rtl_open 


io.h 




jead 


jtljead 


io.h 




_write 


_rtl_write 


io.h 




These routines invoke and terminate 




Process control 


new processes from within 


routines 


another. 








abort 


(process.h) 


exit (process.h) 




Jbeginthread 


(process.h) 


_expand (process.h) 




_c_exit 


(process.h) 


getpid (process.h) 




_cexit 


(process.h) 


jpclose (stdio.h) 




cwait 


(process.h) 


jpopen (stdio.h) 




_endihread 


(process.h) 


raise (signal.h) 




execl 


(process.h) 


signal (signal.h) 




execle 


(process.h) 


spawn! (process.h) 




execlp 


(process.h) 


spawnle (process.h) 




execlpe 


(process.h) 


spawnlp (process.h) 




execv 


(process.h) 


spawnlpe (process.h) 




execve 


(process.h) 


spawnv (process.h) 




execvp 


(process.h) 


spawnve (process.h) 




execvpe 


(process.h) 


spawnvp (process.h) 




_exit 


(process.h) 


spawnvpe (process.h) 
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Console I/O 
routines 



These routines output text to the screen or read from the keyboard. They 
cannot be used in a PM application. 



cgets 

clreol 

clrscr 

cprintf 

cputs 

delline 

getpass 

gettext 

gettextinfo 

gotoxy 

highvideo 

insline 

lowvideo 



(conio.h 
(conio.h 
(conio.h 
(conio.h 
(conio.h 
(conio.h 
(conio.h 
(conio.h 
(conio.h 
(conio.h 
(conio.h 
(conio.h 
(conio.h 



movetext 


(conio.h) 


normvideo 


(conio.h) 


putch 


(conio.h) 


puttext 


(conio.h) 


_setcursortype 


(conio.h) 


textattr 


(conio.h) 


textbackground 


(conio.h) 


textcolor 


(conio.h) 


textmode 


(conio.h) 


ungetc 


(stdio.h) 


wherex 


(conio.h) 


wherey 


(conio.h) 


window 


(conio.h) 





These are time 


conversion an 


Time and date 






routines 








asctime 


(time.h) 




ctime 


(time.h) 




difftime 


(time.h) 




_dos_getdate 


(dos.h) 




_dos_gettime 


(dos.h) 




_dos_setdate 


(dos.h) 




_dos_settime 


(dos.h) 




dostonnix 


(dos.h) 




ftime 


(sys\timeb.h) 




getdate 


(dos.h) 




gettime 


(dos.h) 




gmtime 


(time.h) 




localtime 


(time.h) 



mktime 

setdate 

settime 

stime 

_strdate 

strftime 

_strtime 

TDate 

time 

TTime 

tzset 

unixtodos 



(time.h) 

(dos.h) 

(dos.h) 

(time.h) 

(time.h) 

(time.h) 

(time.h) 

(date.h) 

(time.h) 

(time.h) 

(time.h) 

(dos.h) 



Variable argument .., . , r . x 
list routines with vprintf, etc). 



These routines are for use when accessing variable argument lists (such as 



va_arg 
va end 



(stdarg.h) 
(stdarg.h) 



va start 



(stdarg.h) 
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Index 



TSubString operator 454 

global string operator 452 
string operator 449 
TDate operator 435 
TTime operator 465 

TDate operator 435 
TTime operator 465 

string operator 450 
TDate operator 434 
TTime operator 465 

string operator 449 
TMVectorlmp operator 393 
TSubString operator 453 
TSync operator 458 
TThread operator 461 

string operator 451 
TDate operator 435 
TTime operator 465 

string operator 450 
TDate operator 435 
TSubString operator 454 
TTime operator 465 

string operator 449 
TSubString operator 454 



++ 



TBinarySearchTreelteratorlmp operator 324 
TDate operator 435 

TIBinarySearchTreelteratorlmp operator 326 
TMArrayAsVectorlterator operator 301 
TMDequeAsVectorlterator operator 330 
TMDictionaryAsHashTablelterator operator 34 1 
TMDoubleListlteratorlmp operator 349 
TMHashTablelteratorlmp operator 358 
TMI Array As Vectorlterator operator 307 



TMIDictionaryAsHashTablelterator operator 
344 

TMIDoubleListlterator operator 354 
TMIHashTablelteratorlmp operator 360 
TMIListlteratorlmp operator 369 
TMIVectorlteratorlmp operator 403 
TMListlteratorlmp operator 365 
TMVectorlteratorlmp operator 394 
TTime operator 465 



+= 



string operator 449 
TDate operator 435 
TTime operator 465 

TDate operator 435 

TMDoubleListlteratorlmp operator 349 
TTime operator 465 

TDate operator 435 
TTime operator 465 



« 



global string operator 451 
TDate operator 435 
TTime operator 465 



<= 



string operator 451 
TDate operator 434 
TTime operator 465 

string operator 450 
TDate operator 435 
TMDDAssociation operator 311 
TMDIAssociation operator 313 
TMID Association operator 375 
TMII Association operator 316 
TSubString operator 453 
TTime operator 465 

string operator 451 
TDate operator 435 
TTime operator 465 



» 



global string operator 451 
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string operator 451 
TDate operator 435 
TTime operator 466 

[] 

string operator 449 
TArray operator 306 
TMArrayAs Vector operator 300 
TMIVectorlmp operator 402 
TMVectorlmp operator 393 
TSubString operator 454 

80x86 processors 
functions (list) 476 

0x4E DOS system call 67 



abnormal program termination 152, 426 

abort (function) 10 

abs (complex friend function) 414 

abs (function) 1 1 

absolute value 

complex numbers 21,414 

square 416 
floating-point numbers 60 
integers 11 
long 109 

access 

modes, changing 25, 47, 159 
program, signal types 152 

invalid 152 
read/write 25, 82 
files 12, 34, 134, 187 
permission 135 

access (function) 1 1 

access flags 134, 187 

access permission mask 228 

acos (complex friend function) 414 

acos (function) 12 

acosl (function) 12 

Add 

TBinarySearchTreelmp member function 322 
TIBinarySearchTreelmp member function 325 
TMArrayAs Vector member function 298 
TMBagAsVector member function 318 
TMCVectorlmp member function 396 
TMDictionaryAsHashTable member function 
340 



TMDoubleListlmp member function 347 
TMHashTablelmp member function 357 
TMIArrayAs Vector member function 303 
TMIBagAs Vector member function 320 
TMICVectorlmp member function 404 
TMIDictionaryAsHashTable member function 
342 

TMIDoubleListlmp member function 352 
TMIHashTablelmp member function 359 
TMIListlmp member function 367 
TMISetAs Vector member function 382 
TMListlmp member function 363 
TMSetAs Vector member function 380 

AddAt 

TMArrayAs Vector member function 298 
TMCVectorlmp member function 396 
TMIArrayAs Vector member function 303 

AddAtHead 

TMDoubleListlmp member function 347 
TMIDoubleListlmp member function 352 

AddAtTail 

TMDoubleListlmp member function 347 
TMIDoubleListlmp member function 352 

adjustfield, ios data member 260 

alloc.h (header file) 469 

alloca (function) 13 

allocate, streambuf member function 273 

allocation 

streamable object file buffers and 278, 286 

alphabetic ASCII codes, checking for 103 

alphanumeric ASCII codes, checking for 102 

angles (complex numbers) 415 

app, ios data member 261 

append, string member function 44 1 

arc cosine 12 

arc sine 14 

arctangent 15, 16 

arg (complex friend function) 415 

argc (argument to main) 3 

_argc (global variable) 243 

ARGS.EXE 4 

argument list, variable 232 

conversion specifications and 142 

arguments 

command line, passing to main 3 

wildcards and 5 
command-line, passing to main 243 



482 



Borland C++ for OS/2 Library Reference 



variable number of 
functions (list) 480 
argv (argument to main) 3 
_argv (global variable) 243 
arrays 

of character, attribute information 243 

searching 20, 110 

of time zone names 250 
ArraySize 

TMArray As Vector member function 298 

TMIArrayAs Vector member function 303 
ASCII codes 

alphabetic 103 
lowercase 105 
uppercase 107 

alphanumeric 102 

control or delete 104 

converting 

characters to 224 
date and time to 13 

digits 105 
hexadecimal 107 

functions, list 473 

low 103 

lowercase alphabetic 105 

printing characters 105, 106 

punctuation characters 106 

uppercase alphabetic 107 

whitespace 107 
asctime (function) 13 
asin (complex friend function) 415 
asin (function) 14 
asinl (function) 14 
assert (function) 15 
assert_element 

string member function 448 

TSubString member function 453 
assert.h (header file) 469 
assert_index, string member function 448 
AssertDate, TTime member function 464 
AssertlndexOfMonth, TDate member function 434 
assertion 15 
AssertWeekDayNumber, TDate member function 

434 
assign, string member function 44 1 
assignment suppression, format specifiers 166, 

170, 171 



AsString 

TDate member function 432 

TTime member function 463 
atan (complex friend function) 415 
a tan (function) 15 
atan2 (function) 16 
atan21 (function) 16 
atanl (function) 15 
ate, ios data member 261 
atexit (function) 16 
atof (function) 17 
atoi (function) 18 
atol (function) 18 
_atold (function) 1 7 
attach member functions 

filebuf 256 

fpbase 278 

fstreambase 259 
attribute bits 134, 187 
attribute word 36, 42, 160 
attributes 

characters, arrays of 243 

text 218, 219, 220 

B 

bad 

ios member function 262 

pstream member function 286 
Bad_cast (class) 425 
Badjypeid (class) 425 
banker's rounding 4 12 
base 10 logarithm 116,416 
base, streambuf member function 273 
basefield, ios data member 260 
BCD (binary coded decimal) numbers 411,413 
bed (class constructor) 411, 412 
bcd.h (header file) 469 
before, Type_info member function 428 
BeginDST, TTime member function 463 
Jbeginthread (function) 19 
Between 

TDate member function 432 

TTime member function 463 
binary, ios data member 261 
binary files 

creat and 34 

creattemp and 36 



Index 
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fdopen and 62 
fopen and 73 
freopen and 76 
_fsopen and 80 
opening 63, 73, 76, 80 
and translating 248 
setting 179 
temporary 

naming 217, 223 
opening 223 
binary search 20 
bit mask 81 
bit rotation 

long integer 118 
unsigned char 37 
unsigned integer 159 
bitalloc, ios member function 262 
bits, attribute 36, 41, 42, 134, 161, 187 
blen, streambuf member function 273 
blink-enable bit 219 
Borland C++ 

obsolete definitions 478 
Borland C++, functions, licensing 469 
BoundBase 

TArrayAsVectorlmp member function 305 
TMArray As Vector member function 298 
bp 

ios data member 261 
pstream data member 287 
bsearch (function) 20 
buffers 

default, allocating 286 
files 180, 255, 257 
allocating 278 
creating 278, 279, 282, 283 

pstream 286 
current 278 
keyboard, pushing character to 229 
pointers, pstream 287 
streams and 174, 180, 255, 257 
clearing 69 
flushing 61 
pointers to 287 
writing 69 
system-allocated, freeing 61 
writing data from 284 
BUILDER type, streamable classes and 289 



bytes 



streamable objects and 279, 280, 281, 282, 283, 
284, 290 
swapping 215 



c_str, string member function 442 

cabs (function) 21 

cabsl (function) 21 

calendar format (time) 131 

calloc (function) 22 

CastablelD, TStreamableBase member function 

288 
ceil (function) 22 
ceill (function) 22 
cgets (function) 23 
characters 

alphabetic 103 

alphanumeric 102 

array 280 
global variable 243 

attributes 218,219, 220 

blinking 219 

color, setting 218, 220 

control or delete 104 

converting to ASCII 224 

device 104 

digits 105 

displaying 143, 148, 167 

floating-point numbers and 1 7 

functions (list) 473 

hexadecimal digits 107 

intensity 
high 101 
low 117 
normal 133 

low ASCII 103 

lowercase 225 
checking for 105 
converting to 224, 225 

manipulating header file 470 

newline (\n) 150 

printing 105, 106 

punctuation 106 

pushing 

to input stream 229 
to keyboard buffer 229 
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reading 167 
from console 23 
from keyboard 85, 86 
from streams 64, 85, 86 
stdin 65 
scanning in strings 199, 207 

segment subset 209 
searching 
blocks 126 
strings 196 
streamable objects and 284 
uppercase 

checking for 107 
converting to 225, 226 
whitespace 107 
writing 
to screen 148 
to streams 74, 148 
chdir (function) 24 
_chdrive (function) 24 
CHECK macro 420 
checks.h (header file) 469 
CHECKX macro 421 
child processes 56, 188 
file handles 468 
functions (list) 479 
header file 471 
created by exec (function) 6 
created by spawn (function) 6 
chmod (function) 25 
chsize (function) 26 
class diagnostics 419 
CHECK macro 419 
CHECKX macro 419 
PRECONDITION macro 419 
PRECONDITIONX macro 419 
TRACE macro 419 
TRACEX macro 419 
WARN macro 419 
WARNX macro 419 
classes 

names, read/write prefix/suffix 281 
registering 280, 284, 289 
writing to streams 285 
clear 

ios member function 262 
pstream member function 286 



_clear87 (function) 26 
clearerr (function) 27 
clearing 

screens 29 

to end of line 29 
clock (function) 27 
close (function) 28 
Close, TFile member function 438 
close member functions 

filebuf 256 

fpbase 278 

fstreambase 259 
closedir (function) 28 
clreol, conbuf member function 253 
clreol (function) 29 
clrscr (function) 29 
clrscr member functions 

conbuf 253 

constream 255 
co-routines, task states and 117 
colors and palettes 

background color, text 218,219 

setting, character 218, 220 
command-line arguments, passing to main 243 
command-line compiler, Pascal calling conventions, 

option (-p) 6 
communications, ports, checking for 104 
compare, string member function 44 1 
CompareTo 

TDate member function 432 

TTime member function 463 
comparing two values 124, 129 
comparison function, user-defined 151 
compile- time limitations, header file 470 
complex (class constructor) 414 
complex.h (header file) 469 
complex numbers 

absolute value 21 
square of 416 

angles 415 

conjugate of 415 

constructor for 414 

conversion to real 414 

functions (list) 477 

header file 469 

imaginary portion 416 

logarithm 416 
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polar function 416 

real portion 416 
COMSPEC environment variable 215 
conbuf (class) 253 
concatenated strings 196, 204 
CondFunc typedef 297, 302, 317, 320, 327, 331, 

334, 337, 346, 352, 362, 367, 383, 386, 391, 400 
conditions, testing 15 
conio.h (header file) 470 
conj (complex friend function) 415 
conjugate (complex numbers) 415 
console 

checking for 104 

header file 470 

reading and formatting 
characters 23 
input 37 
constants 

DOS (header file) 470 

open function (header file) 470 

symbolic (header file) 472 

UNIX compatible (header file) 472 

used by function setf 260 
constrea.h (header file) 470 
constream (class) 255 
constructors 

complex numbers 414 

conbuf 253 

filebuf 256 

fpbase 278 

fstream 258 

fstreambase 258 

ifpstream 279 

ifstream 259 

iostream 264 

iostream_withassign 265 

ipstream 279, 281 

istream 265 

istream_withassign 267 

istrstream 268 

ofpstream 282 

ofstream 268 

opstream 283, 285 

ostream 269 

ostream_withassign 270 

ostrstream 270 

pstream 286, 287 



streambuf 262, 271 
strstream 276 
strstreambase 274 
strstreambuf 275 
TStreamableClass 289 
contains, string member function 442 
_control87 (function) 30 
control-break 

software signal 152 
control characters, checking for 104 
control word, floating point 30 
conversions 

binary coded decimal 411,413 
complex numbers 414 
date and time 13 

to calendar format 131 

DOS to UNIX format 53 

to Greenwich mean time 95 

header file 472 

to string 38 

to structure 113 

UNIX to DOS format 230 
double 

to integer and fraction 131 

to mantissa and exponent 77 

strings to 210 
floating point 

strings to 1 7 

to string 54, 61, 84 
format specifiers 142, 143, 146 
functions (list) 473 
header file 472 
integer 

strings to 18 

to ASCII 224 

to string 108 
long double, strings to 210 
long integer 

strings to 18,211,213 

to string 120, 228 
lowercase to uppercase 213, 225, 226 
specifications (printf) 142 
strings 

date and time to 38 

integers to 108 

to double 210 

to floating point 1 7 
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to integer 18 

to long double 210 

to long integer 18, 21 1, 213 

to unsigned long integer 213 

unsigned long integer 
strings to 213 
to string 228 

uppercase to lowercase 204, 224, 225 
coordinates 

cursor position 96, 239 

screens, text mode 93 
copy, string member function 442 
cos (complex friend function) 415 
cos (complex numbers) 415 
cos (function) 31 

cosh (complex friend function) 415 
cosh (complex numbers) 475 
cosh (function) 31 
coshl (function) 31 
cosine 31,415 

hyperbolic 31 

complex numbers 415 

inverse 12 
cosl (function) 31 

Count, TMCVectorlmp member function 396 
country (function) 32 
country-dependent data 32, 111, 176 
cow, string member function 448 
cprintf (function) 33 

format specifiers 141 
cputs (function) 33 
creat (function) 34 
creatnew (function) 35 
creattemp (function) 36 
_crotl (function) 37 
_crotr (function) 37 
cscanf (function) 37 

format specifiers 165 
cstring.h (header file) 470 
ctime (function) 38 
_ctype (global variable) 243 
ctype.h (header file) 470 
currency symbols 32, 111, 176 
Current 

TBinarySearchTreelteratorlmp member function 

324 

TIBinarySearchTreelmp member function 326 



TMArrayAsVectorlterator member function 301 

TMDequeAsVectorlterator member function 

329 

TMDictionaryAsHashTablelterator member 

function 341 

TMDoubleListlteratorlmp member function 349 

TMHashTablelteratorlmp member function 358 

TMIArrayAsVectorlterator member function 

306 

TMIDictionaryAsHashTablelterator member 

function 343 

TMIDoubleListlteratorlmp member function 

354 

TMIHashTablelteratorlmp member function 

360 

TMIListlteratorlmp member function 368 

TMIVectorlteratorlmp member function 402 

TMListlteratorlmp member function 365 

TMVectorlteratorlmp member function 394 
current drive number 89 
cursor 

appearance, selecting 1 75 

position in text window 96 
returning 239 
cwait (function) 38 



data 

country-dependent, supporting 32, 111, 176 

reading from streams 75, 77, 234, 236 
stdin 165, 235 

returning from current environment 90 

security 91 

writing to current environment 149 
Data, TMDequeAs Vector data member 329 
data public members 

TMDoubleListElement 345 

TMListElement 362 
data types 

defining header file 471 

time_t (header file) 472 
date 

file 48, 90 

global variable 244 

international formats 32 

system 13, 38, 83, 95, 1 13 
converting from DOS to UNIX 53 
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converting from UNIX to DOS 230 
getting 45 
setting 45, 195 
date functions (list) 480 
Day, TDate member function 432 
_daylight (global variable) 244 

setting value of 227 
daylight saving time 

adjustments 38, 244 

setting 227 
DayName, TDate member function 432 
DayOfMonth, TDate member function 432 
DayOfWeek, TDate member function 432 
DaysInYear, TDate member function 433 
DayTy, TDate type definition 431 
DayWithinMonth, TDate member function 433 
_ _DEBUG debugging symbol 419 
debugging 

classes 419 
debugging, macros (header file) 469 
dec, ios data member 261 
delete 

TMDoubleListElement operator 346 

TMListElement operator 362 
DeleteElements 

TMDD Association member function 311 

TMID Association member function 314 

TMII Association member function 316 
DeleteNode 

TBinarySearchTreelmp member function 323 

TIBinarySearchTreelmp member function 325 
DeleteType, TShouldDelete data member 408 
deletion 

characters, checking for 104 

directories 158 

file 156, 230 

line 29, 40 
delline, conbuf member function 253 
delline (function) 40 
DelObj 

TShouldDelete member function 408 
DELTA macro 291 

TStreamableClass 289 
Destroy 

TMArrayAs Vector member function 298 

TMIArrayAsVector member function 303 



destructor 
opstream 283 
pstream 286 

Detach 

TBinarySearchTreelmp member function 322 
TIBinarySearchTreelmp member function 325 
TMArrayAs Vector member function 298 
TMBag As Vector member function 318 
TMCVectorlmp member function 396 
TMDictionaryAsHashTable member function 
340 

TMDoubleListlmp member function 347 
TMHashTablelmp member function 357 
TMIArrayAsVector member function 303 
TMIBagAs Vector member function 320 
TMIDictionaryAsHashTable member function 
343 

TMIDoubleListlmp member function 352 
TMIHashTablelmp member function 359 
TMIListlmp member function 367 
TMListlmp member function 363 

DetachAtHead 

TMDoubleListlmp member function 347 
TMListlmp member function 363 

DetachAtHead, TMIDoubleListlmp member function 
352 

DetachAtTail, TMIDoubleListlmp member function 
352 

device 

character 104 
type checking 104 

DIAG_DECLARE_GROUP 422 

DIAG_DEFINE_GROUP macro 422 

DIAG_ENABLE macro 422 

DIAG_GETLEVEL macro 422 

DIAGJSENABLED macro 422 

DIAG_SETLEVEL macro 422 

diagnostics 
class 419 
header file 469 
preprocessor symbols 419 

difftime (function) 40 

dir.h (header file) 470 

direct.h (header file) 470 

directories 
creating 130 
current 57, 189 
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changing 24 
returning 86, 87, 88 

deleting 158 

functions (list) 473 

header file 470 

searching 28, 43, 44, 67, 68, 135, 155, 158, 172, 
173 
directory stream 

closing 28 

opening 135 

reading 155 

rewinding 158 
dirent.h (header file) 470 
disk drives 

current number 46, 89 

setting 24 
disks 

space available 46, 88 

writing to, verification 95, 181 
div (function) 40 
division, integers 40, 110 
doallocate, strstreambuf member function 275 
DOS 

date and time 45 

converting to UNIX format 53 
converting UNIX to 230 
setting 94 

environment, adding data to 149 

file attributes, search 67 

functions (list) 476 

header file 470 

system calls 
0x4E 67 

verify flag 94 
_dos_close (function) 41 
_dos_creat (function) 4 1 
DosCreateThread (function) 7 
_dos_crearnew (function) 42 
_doserrno (global variable) 245 
_dos_findfirst (function) 43 
_dos_findnext (function) 44 
_dos_getdate (function) 45 
_dos_getdiskfree (function) 46 
_dos_getdrive (function) 46 
_dos_getfileattr (function) 47 
_dos_getftime (function) 48 
_dos_gettime (function) 49 



dos.h (header file) 470 

_dos_open (function) 49 

_dos_read (function) 50 

_dos_setdate (function) 45 

_dos_setdrive (function) 46 

_dos_setfileattr (function) 47 

_dos_setftime (function) 48 

_dos_settime (function) 49 

dostounix (function) 53 

_dos_write (function) 52 

dup (function) 53 

dup2 (function) 54 

dynamic_cast (exception) 425 

dynamic memory allocation 22, 76, 121, 155, 194 



eatwhite, istream member function 267 
eback, streambuf member function 273 
ebuf, streambuf member function 273 
echoing to screen 85, 86 
ecvt (function) 54 
editing, block operations 

copying 126, 128 

searching for character 126 
egptr, streambuf member function 273 
encryption 91 
end of file 

checking 55, 63, 154 

resetting 27 
end of line, clearing to 29 
_endthread (function) 55 
enum open_mode, ios data member 261 
env (argument to main) 3 
environ (global variable) 4 
_environ (global variable) 244 
environment 

operating system 
header file 470 

variables 244 
COMSPEC 215 
PATH 57, 189 
eof 

ios member function 262 

pstream member function 286 
eof (function) 55 
epptr, streambuf member function 273 
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EqualTo 

TBinarySearchTreelmp member function 323 

TIBinarySearchTreelmp member function 325 
equations, polynomial 139 
errno (global variable) 245 
errno.h (header file) 470 
error codes 245 

error handlers, math, user-modifiable 122 
errors 

detection, on stream 63 

DOS 

mnemonics 245 

indicators, resetting 27 

locked file 114 

messages 

perror function 137 
pointer to, returning 200 
printing 136, 245 

messages under Presentation Manager 7 

mnemonics for codes 470 

pop-up screens 7 

read /write 63 

streams and 286 
ErrorType, TThreadError data member 461 
European date formats 32 
except.h (header file) 470 

exception handlers, numeric coprocessors 27, 195 
exception handling 

exception names 250 

files 250 

global variables 250 

messages 430 

predefined exceptions 425, 429, 430 

set_terminate (function) 426 

set_unexpected (function) 427 

terminate (function) 427 

unexpected (function) 429 
exceptions 

Bad_cast (class) 425 

Badjypeid (class) 425 

floating-point 30 

memory allocation 426, 429 

xalloc 426, 429 

xmsg (class) 430 
excpt.h (header file) 470 
exec. . . 

(functions) file handles 468 



execl (function) 56 

execle (function) 56 

execlp (function) 56 

execlpe (function) 56 

execution, suspending 186 

execv (function) 56 

execve (function) 56 

execvp (function) 56 

execvpe (function) 56 

exit (function) 16, 23, 58 

_exit (function) 58 

exit codes 11 

exit status 58, 59 

exp (complex friend function) 415 

exp (function) 59 

_expand (function) 60 

expl (function) 59 

exponential (complex numbers) 415 

exponents 

calculating 59, 140, 141 

double 77, 109 
external, undefined 478 



fabs (function) 60 

fabsl (function) 60 

fail 

ios member function 262 
pstream member function 286 

f close (function) 61 

fcloseall (function) 61 

fcntl.h (header file) 470 

fcvt (function) 61 

id, filebuf member function 256 

fdopen (function) 62 

feof (function) 63 

ferror (function) 63 

fflush (function) 64 

fgetc (function) 64 

fgetchar (function) 65 

fgetpos (function) 65 

fgets (function) 65 

fields, input 168, 171 

file modes 

changing 25, 47, 159 
default 36, 42, 43,161 
global variables 248 
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setting 179,248 
text 62, 73, 76, 80 
translation 34, 36, 248 
file permissions 228 
filebuf (class) 255 
filelength (function) 66 
fileno (function) 66 
FileNull, TFile data member 436 
files 
access 

determining 11 

flags 134, 187 

permission 25 
ARGS.EXE 4 

attaching 278, 279, 282, 283 
attribute bits 134, 187 
attribute word 160 
attributes 34 

access mode 47, 159 

file sharing 50, 163 

searching directories and 43, 67 

setting 36, 41,42, 161 
buffers 180 

allocating 278 

current 278 

input and output 255, 257 

line 181 
closing 28, 41,61, 76, 160, 278 
date 48, 90 
deleting 156, 230 
end of 

checking 55, 63, 154 

resetting 27 
file descriptor fd (function) 256 
file pointer reposition 257 
handles 28, 41, 135, 160 

duplicating 53, 54 

linking 468 

linking to streams 62 

returning 66 
header 9 

information on, returning 81 
locking 114, 231 

modes, setting 278, 279, 282, 283 
names 

unique 130,217,223 
new 34, 35, 36, 41, 42, 161 



open, statistics on 81 

opening 49, 134, 162, 278, 279, 283 

for update 63, 73, 77, 80 
in binary mode 223 

for writing 282 

modes 261, 279, 283 
default 256 

openprot 256 

shared 79, 186, 187 

streams and 72, 76, 79 
overwriting 34 
position seeking 260 
reading 34, 50, 154, 163 

and formatting input from 77, 165, 234, 235, 

236 

characters from 64, 85 

data from 75 

header file 470 

integers from 95 

strings from 65 
renaming 157 
replacing 76 
rewriting 34, 41,42,161 
scratch 21 7, 223 

opening 223 
security 91 
seek an offset 257 
sharing 

attributes 50, 163 

header file 471 

locks 114,231 

opening shared files 79, 186, 187 

permission 80, 187 
size 26 

returning 66 
statistics 81 

streams, C++ operations 258 
temporary 217, 223 

opening 223 

removing 159 
time 48, 90 
unlocking 231 
WILDARGS.OBJ 5, 6 
writing 52, 84, 164,240 

attributes 34 

characters to 74 

formatted output to 74, 141, 233, 234 
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header file 470 
strings to 75 

fill, ios member function 262 

Find 

TBinarySearchTreelmp member function 323 

TIBinarySearchTreelmp member function 325 

TMArray As Vector member function 298 

TMBagAs Vector member function 318 

TMCVectorlmp member function 396 

TMDictionaryAsHashTable member function 

340 

TMHashTablelmp member function 357 

TMIArrayAsVector member function 304 

TMIBagAs Vector member function 320 

TMICVectorlmp member function 404 

TMIDictionaryAsHashTable member function 

343 

TMIHashTablelmp member function 359 

find 

ipstream member function 279 
string member function 442 

find_first_not_of, string member function 443 

find_first_of, string member function 443 

find_last_not_of, string member function 444 

find_last_of, string member function 444 

FindBase, TStreamableBase member function 288 

FindDetach 

TMDoubleListlmp member function 348 
TMISDoubleListlmp member function 355 
TMISListlmp member function 370 
TMListlmp member function 364 
TMSDoubleListlmp member function 350 

findfirst (function) 67 

findnext (function) 68 

findObject, opstream member function 283 

FindPred 

TMDoubleListlmp member function 348 
TMIDoubleListlmp member function 353 
TMISListlmp member function 370 
TMListlmp member function 364 
TMSDoubleListlmp member function 350 

findVB, opstream member function 283 

FirstDayOfMonth, TDate member function 433 

FirstThat 

TMArrayAs Vector member function 299 
TMDequeAsDoubleList member function 334 
TMDequeAsVector member function 327 



TMDoubleListlmp member function 347 

TMIArrayAsVector member function 304 

TMIBagAs Vector member function 320 

TMIDequeAsDoubleList member function 337 

TMIDequeAs Vector member function 331 

TMIDoubleListlmp member function 352 

TMIListlmp member function 367 

TMIQueueAsDoubleList member function 378 

TMIQueueAsVector member function 373 

TMIStackAs Vector member function 386 

TMIVectorlmp member function 400 

TMListlmp member function 363 

TMQueueAsDoubleList member function 376 

TMQueueAsVector member function 371 

TMStackAs Vector member function 384 

TMVectorlmp member function 391 
fixed, ios data member 261 
flags 

DOS verify 94 

format specifiers 142, 144, 145 

format state 287 

ios member function 262 

operating system verify 181 

read/write 134, 187 
float.h (header file) 470 
_floatconvert (global variable) 247 
floatfield, ios data member 260 
floating point 

absolute value of 60 

binary coded decimal 411,413 

characters and 1 7 

control word 30 

displaying 143, 170 

double, exponents 109 

exceptions 30 

format specifiers 143, 167, 170 

formats 247 

functions (list) 477 

header file 470 

I/O 247 

infinity 30 

math package 73 

modes 30 

precision 30 

reading 167 

software signal 152 

status word 26, 194 
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floor (function) 69 

floor! (function) 69 

Flush 

TBinarySearchTreelmp member function 323 
TFile member function 438 
TIBinarySearchTreelmp member function 325 
TMArray As Vector member function 299 
TMBagAs Vector member function 318 
TMDequeAsDoubleList member function 334 
TMDequeAs Vector member function 327 
TMDictionaryAsHashTable member function 
340 

TMDoubleListlmp member function 347 
TMHashTablelmp member function 357 
TMIArray As Vector member function 304 
TMIBagAs Vector member function 320 
TMIDequeAsDoubleList member function 337 
TMIDequeAs Vector member function 331 
TMIDictionaryAsHashTable member function 
343 

TMIDoubleListlmp member function 353 
TMIHashTablelmp member function 359 
TMIQueueAsDoubleList member function 378 
TMIQueueAsVector member function 374 
TMIStackAs Vector member function 386 
TMIVectorlmp member function 401 
TMListlmp member function 363 
TMQueueAsDoubleList member function 376 
TMQueueAs Vector member function 371 
TMStackAs Vector member function 384 
TMVectorlmp member function 392 

flush 

opstream member function 283 
ostream member function 269 

flushall (function) 69 

flushing streams 64, 69 

_fmemmove (function) 128 

fmod (function) 70 

_fmode (global variable) 248 

fmodl (function) 70 

fnmerge (function) 70 

fnsplit (function) 71 

fopen (function) 72 

ForEach 

TBinarySearchTreelmp member function 323 
TIBinarySearchTreelmp member function 325 
TMArray As Vector member function 299 



TMBagAs Vector member function 318 
TMDequeAsDoubleList member function 334 
TMDequeAs Vector member function 327 
TMDictionaryAsHashTable member function 
340 

TMDoubleListlmp member function 347 
TMIArray As Vector member function 304 
TMIBagAs Vector member function 321 
TMIDequeAsDoubleList member function 337 
TMIDequeAs Vector member function 33 1 
TMIDictionaryAsHashTable member function 
343 

TMIDoubleListlmp member function 353 
TMIHashTablelmp member function 357, 359 
TMIListlmp member function 367 
TMIQueequeAs Vector member function 374 
TMIQueueAsDoubleList member function 378 
TMIStackAs Vector member function 387 
TMIVectorlmp member function 401 
TMListlmp member function 363 
TMQueueAsDoubleList member function 376 
TMQueueAs Vector member function 372 
TMStackAs Vector member function 384 
TMVectorlmp member function 392 
format flags 260, 26 1 

state 287 
format specifiers 

assignment suppression 166, 170, 171 
characters 143, 167 

type 166, 167 
conventions 

display 144 

reading 168 
conversion type 142, 143, 146 
cprintf 141 
cscanf 165 
F and N 142 
flags 142, 144 

alternate forms 745 
floating-point 143, 167, 170 
fprintf 141 
fscanf 165 

inappropriate character in 1 71 
input fields and 168, 171 
integers 143, 167 
modifiers 

argument-type 166, 171 
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input-size 142, 143,147 
size 166, 171 

pointers 144, 168 

precision 142, 143, 146 

printf 141 

range facility shortcut 169 

scanf 165 

sprintf 141, 192 

sscanf 165 

strings 143, 167 

vfprintf 141 

vf scanf 165 

vprintf 141 

vscanf 165 

vsprintf 141 

vsscanf 165 

width 
printf 142, 145 
scanf 166, 170, 171 
format strings 

input 165 

output 142 
formatting 

console input 37 

cprintf 33 

cscanf 37 

fprintf 74 

fscanf 77 

output 33 

printf 141 

scanf 165 

sprintf 192 

sscanf 193 

strings 192, 236 

time 201 

vfprintf 233 

vfscanf 234 

vprintf 234 

vscanf 235 

vsprintf 236 

vsscanf 236 
fpbase class 278 
_fpreset (function) 73 
fprintf (function) 74 

format specifiers 141 
fputc (function) 74 
fputchar (function) 74 



fputs (function) 75 

frame base pointers as task state 11 7, 176 

fread (function) 75 

freadBytes, ipstream member function 279 

freadString, ipstream member function 280 

free (function) 76 

freeze, strstreambuf member function 275 

freopen (function) 76 

frexp (function) 77 

frexpl (function) 77 

fscanf (function) 77 

format specifiers 165 
fseek (function) 78 
fsetpos (function) 79 
_fsopen (function) 79 
fstat (function) 81 
fstream (class) 257 
fstream.h (header file) 470 
fstreambase (class) 258 
ftell (function) 82 
ftime (function) 83 
ftruncate (function) 226 
Jfullpath (function) 83 
functions 

bed (header file) 469 

Borland C++, licensing 469 

child processes 479 
header file 471 

classification 473 

comparing two values 124 

comparison, user-defined 151 

complex numbers 477 
header file 469 

console (header file) 470 

conversion 473 

date and time 480 
header file 472 

diagnostic 474 

directories 473 
header file 470 

file sharing (header file) 471 

floating point (header file) 470 

fstream (header file) 470 

generic (header file) 470 

goto 478 
header file 471 

integer 477 
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international 

header file 471 

information 478 
I/O 474 

header file 470 
iomanip (header file) 470 
iostream (header file) 470 
listed by topic 472-480 
locale 478 
mathematical 477 

header file 471 
memory 476 

allocating and checking 478 

header file 471 
obsolete names 479 
operating system 476 
process control 479 
signals (header file) 471 
stdiostr (header file) 471 
strings 476 

strstrea (header file) 472 
variable argument lists 480 
windows 480 

with multiple prototypes 472 
fwrite (function) 84 

fwriteBytes, opstream member function 283 
fwriteString, opstream member function 283 



gbump, streambuf member function 273 

gcount, istream member function 265 

gcvt (function) 84 

generic.h (header file) 470 

Get 

TMIQueueAsDoubleList member function 378 
TMIQueueAsVector member function 374 
TMQueueAsDoubleList member function 376 
TMQueueAs Vector member function 372 

get, istream member function 265, 266 

get_at 

string member function 444 
TSubString member function 452 

get_case_sensitive_flag, string member function 
444 

geMnitialjrapacity, string member function 444 

get_max_waste, string member function 444 

get_paranoid_check, string member function 444 



get_resize_increment, string member function 444 

get_skipwhitespace_flag / string member function 
445 

getc (function) 85 

getch (function) 85 

getchar (function) 86 

getche (function) 86 

getcurdir (function) 86 

getcwd (function) 87 

getdate (function) 45 

_getdcwd (function) 88 

GetDelta 

TMCVectorlmp member function 396 
TMIVectorlmp member function 401 
TMVectorlmp member function 392 

getdfree (function) 88 

getdisk (function) 89 

_getdrive (function) 89 

getenv (function) 90 

GetErrorType, TThreadError member function 462 

getftime (function) 90 

GetHandle, TFile member function 438 

GetltemsInContainer 

TBinarySearchTreelmp member function 323, 

325 

TMArray As Vector member function 299 

TMBag As Vector member function 318 

TMDequeAsDoubleList member function 335 

TMDequeAs Vector member function 328 

TMDictionaryAsHashTable member function 

340 

TMDoubleListlmp member function 353 

TMHashTablelmp member function 357 

TMIArray As Vector member function 304 

TMIBagAs Vector member function 321 

TMIDequeAsDoubleList member function 337 

TMIDequeAs Vector member function 332 

TMIDictionaryAsHashTable member function 

343 

TMIHashTablelmp member function 360 

TMIQueueAsDoubleList member function 378 

TMIQueueAsVector member function 374 

TMQueueAsDoubleList member function 376 

TMQueueAs Vector member function 372 

TMStackAs Vector member function 384, 387 

GetLeft 

TMDequeAsDoubleList member function 335 
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TMDequeAs Vector member function 328 

TMIDequeAsDoubleList member function 337 

TMIDequeAs Vector member function 332 
getline 

global string function 452 

istream member function 266 
GetObject, TStreamer member function 290 
getpass (function) 91 
getpid (function) 92 

GetPriority, TThread member function 460 
GetRight 

TMDequeAsDoubleList member function 335 

TMDequeAs Vector member function 328 

TMIDequeAsDoubleList member function 337 

TMIDequeAs Vector member function 332 
gets (function) 92 
GetStatus 

TFile member function 438 

TThread member function 460 
gettext (function) 92 
gettextinfo (function) 93 
gettime (function) 94 
getverify (function) 94 
getVersion, ipstream member function 280 
getw (function) 95 
global variables 243 

Jileinfo 247 

_argc 243 

_argv 243 

arrays, character 243 

command-line arguments 243 

_ctype 243 

_daylight 244 
setting value of 227 

_doserrno 245 

environ 4 

_environ 244 

errno 245 

file mode 248 

_floatconvert 247 

_fmode 248 

main function and 243 

_new_handler 248 

obsolete names 478 

operating system environment 244 

_osmajor 249 
osminor 249 



_osversion 249 

printing error messages 245 

_sys_errlist 245 

_sys_nerr 245 

time zones 244, 250 
setting value of 227 

_timezone 250 

setting value of 227 

_tzname 250 

setting value of 227 

undefined 478 

_version 251 
gmtime (function) 95 
good 

ios member function 263 

pstream member function 286 
goto, nonlocal 116, 175 
goto statements 

functions (list) 478 

header file 471 
gotoxy, conbuf member function 254 
gotoxy (function) 96 
gptr, streambuf member function 273 
graphics drivers, modes, text 92, 93 
Greenwich mean time (GMT) 38, 40, 83 

converting to 95 

global variable 250 

time zones and 227, 250 
Grow 

TMArrayAsVector member function 299 

TMIArray As Vector member function 305 

H 

handlers 

exception 27, 195 
hardware 

checking for presence of 104 
device type 104 
Hash 

TDate member function 433 

TTime member function 463 
hash, string member function 445 
HashTable, TMDictionaryAsHashTable data member 

339 
HashValue 

TMDD Association member function 311 

TMDIAssociation member function 313 
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TMID Association member function 314 

TMIIAssociation member function 316 
HasMember 

TMArray As Vector member function 299 

TMBagAs Vector member function 318 

TMIArray As Vector member function 304 

TMIBagAs Vector member function 321 
Head 

TMDoubleList data member 348 

TMListlmp data member 364 
header files 9, 469-472 

described 469 

floating point 470 

reading and writing 470 

sharing 471 
heap 

allocating memory from 22, 76, 121, 155 

checking 97, 98 

free blocks 
checking 97 
filling 99, 100 

memory freeing in 76 

nodes 98 

reallocating memory in 155 

walking through 100, 161 
_heapadd (function) 97 
heapcheck (function) 97 
heapcheckfree (function) 97 
heapchecknode (function) 98 
_heapchk (function) 98 
_HEAPEMPTY 101 
JHEAPEND 100,101 
_HEAPOK 100 
heapfillfree (function) 99 
_heapmin (function) 99 
_HEAPOK 101 
_heapset (function) 100 
heapwalk (function) 100 
hex, ios data member 261 
hexadecimal digits, checking for 107 
hierarchy, streams 277 
high intensity 101 

highvideo, conbuf member function 254 
highvideo (function) 101 
Hour, TTime member function 463 
HourGMT, TTime member function 463 
HowToPrint, TDate type definition 431 



hyperbolic cosine 31 
hyperbolic sine 185 
hyperbolic tangent 216,417 
hypot (function) 101 
hypotenuse 101 
hypotl (function) 101 

I 

ID, process 92 

ifpstream class 278 

ifstream (class) 259 

ignore, istream member function 266 

illegal instruction, software signal 152 

imag (complex friend function) 416 

in, ios data member 261 

in_avail, streambuf member function 272 

IndexOfMonth, TDate member function 433 

indicator 

end-of-file 27, 55, 63, 154 

error 27 
infinity, floating point 30 
init 

ios member function 264 

pstream member function 288 
initial_capacity, string member function 445 
initialization 

file pointers 157 

memory 129 

random number generator 153, 193 

strings 207, 208 
inline optimization 474 
input 

console, reading and formatting 37 

fields 168 

format specifiers and 171 

from streams 77, 234, 236 

formatting 77, 165, 234, 235, 236 
pushing characters onto 229 
stdin 165, 235 
terminating 172 
insert, string member function 445 
InsertEntry 

TMArray As Vector member function 299 

TMIArrayAs Vector member function 305 
insline (conbuf member function) 254 
insline (function) 102 
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int 

TBinarySearchTreelteratorlmp operator 324 

TIBinarySearchTreelteratorlmp operator 326 

TMArrayAsVectlterator operator 307 

TMDequeAsVectorlterator operator 330 

TMDictionaryAsHashTablelterator operator 34 1 

TMDoubleListlteratorlmp operator 349 

TMHashTablelteratorlmp operator 358 

TMIDictionaryAsHashTablelterator operator 

344 

TMIHashTablelteratorlmp operator 360 

TMIVectorlteratorlmp operator 403 

TMListlteratorlmp operator 365 

TMVectorlteratorlmp operator 394 
integers 

absolute value 7 7 

displaying 743 

division 40 
long integers 7 70 

format specifiers 743, 167 

functions (list) 477 

long 
absolute value of 709 
division 7 70 
rotating 7 73 

ranges, header file 470 

reading 95, 167 

rotating 118,159 

writing to stream 757 
integrated environment, wildcard expansion and 6 
intensity 

high 707 

low 777 

normal 733 
internal, ios data member 261 
international 

character sets 777 

code pages 777 

code sets 7 77 

country-dependent data 32 
setting 111,176 

currency symbol position 7 12 

date formats 32 

decimal point 744, 168 

default category 779 

locales supported 7 76 

specify a category 7 79 



international information 

functions (list) 478 

header file 477 
interrupts 

software 
signal 752 
invalid access to storage 752 
inverse cosine (complex numbers) 474 
inverse sine (complex numbers) 475 
inverse tangent 16 

complex numbers 475 
io.h (header file) 470 
I/O 

buffers 774 

characters, writing 748 

floating-point 
formats, linking 247 
numbers 247 

functions (list) 474 

integers, writing 757 

keyboard 85, 86 
checking for keystrokes 703 

low level header file 470 

screen 33 
writing to 33, 148 

streams 63, 73, 77, 80, 229 
iomanip.h (header file) 470 
ios (class) 260 
ios data members 260 
iostream (class) 264 
iostream.h (header file) 470 
iostream_withassign (class) 264 
ipfx, istream member function 266 
ipstream class 279 

friends 282 
is_null 

String member function 445 

TSubString member function 453 
is_open, filebuf member function 256 
isalnum (function) 702 
isalpha (function) 703 
isascii (function) 703 
isatty (function) 704 
iscntrl (function) 704 
isdigit (function) 705 
IsDST, TTime member function 463 
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IsEmpty 

TBinarySearchTreelmp member function 323, 
325 

TMArrayAs Vector member function 299 
TMBagAsVector member function 318 
TMDequeAsDoubleList member function 335 
TMDequeAs Vector member function 328 
TMDictionaryAsHashTable member function 
340 

TMDoubleListlmp member function 347 
TMHashTablelmp member function 357 
TMIArray As Vector member function 304 
TMIBagAs Vector member function 321 
TMIDequeAsDoubleList member function 338 
TMIDequeAs Vector member function 332 
TMIDictionaryAsHashTable member function 
343 

TMIDoubleListlmp member function 353 
TMIHashTablelmp member function 360 
TMIQueueAsDoubleList member function 378 
TMIQueueAs Vector member function 374 
TMIStackAs Vector member function 387 
TMListlmp member function 363 
TMQueueAsVector member function 372 
TMQuueAsDoubleList member function 376 
TMStackAs Vector member function 384 

IsFull 

TMArrayAs Vector member function 299 
TMBagAsVector member function 318 
TMDequeAsDoubleList member function 335 
TMDequeAsVector member function 328 
TMIArray As Vector member function 304 
TMIBagAs Vector member function 321 
TMIDequeAsDoubleList member function 338 
TMIDequeAsVector member function 332 
TMIQueueAsDoubleList member function 378 
TMIQueueAs Vector member function 374 
TMIStackAs Vector member function 387 
TMQueueAsDoubleList member function 376 
TMQueueAsVector member function 372 
TMStackAs Vector member function 384 

isgraph (function) 105 

islower (function) 105 

IsOpen, TFile member function 438 

isprint (function) 106 

ispunct (function) 106 

isspace (function) 107 



istream (class) 265 
istream_withassign (class) 267 
istrstream (class) 267 
isupper (function) 107 
IsValid 

TDate member function 433 

TTime member function 464 
isxdigit (function) 107 
ItemAt 

TMArrayAs Vector member function 300 

TMIArrayAs Vector member function 305 
IterFunc typedef 297, 302, 317, 320, 327, 331, 334, 

337, 346, 352, 362, 367, 383, 386, 391, 400 
itoa (function) 108 



Japanese date formats 32 

Jday, TDate member function 433 

JulTy, TDate type definition 431 

K 

kbhit (function) 108 

Key 

TMDD Association member function 311 
TMDIAssociation member function 313 
TMID Association member function 315 
TMIIAssociation member function 316 

keyboard 

buffer, pushing characters back into 229 
I/O 85, 86 

checking for 703 
reading characters from 85, 86 

Key Data, TMID Association data member 314 

keystrokes, checking for 108 



labs (function) 109 

LastThat 

TMArrayAs Vector member function 299 
TMDequeAsDoubleList member function 335 
TMDequeAsVector member function 328 
TMDoubleListlmp member function 347 
TMIArray As Vector member function 304 
TMIBagAs Vector member function 321 
TMIDequeAsDoubleList member function 338 
TMIDequeAsVector member function 332 
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TMIDoubleListlmp member function 353 
TMIListlmp member function 368 
TMIQueueAsDoubleList member function 378 
TMIQueueAs Vector member function 374 
TMIStackAs Vector member function 387 
TMIVectorlmp member function 40 1 
TMListlmp member function 364 
TMQueueAsDoubleList member function 376 
TMQueueAs Vector member function 372 
TMStackAs Vector member function 384 
TMVectorlmp member function 392 

lconv structure 1 11 

ldexp (function) 109 

ldexpl (function) 109 

ldiv (function) 110 

Leap, TDate member function 433 

left, ios data member 261 

Left, TMDequeAs Vector data member 329 

length 

of files 26, 66 
of strings 203 

Length, TFile member function 438 

length member functions 
string 445 
TSubString 453 

LessThan 

TBinarySearchTreelmp member function 323 
TIBinarySearchTreelmp member function 325 

If ind (function) 110 

libraries 

entry headings 9 
multi-thread support 7 

LIBC 7 

LIBCMT 7 

Lim, TMVectorlmp data member 393 

Limit 

TMIVectorlmp member function 401 
TMVectorlmp member function 392 

limits. h (header file) 470 

line-buffered files 181 

linear searches 110, 118 

lines 

blank, inserting 102 
clearing to end of 29 
deleting 29, 40 

local standard time 38, 40, 83, 95, 1 13 



locale 

current 111 

dynamically loadable 178 

enabling 178 

environment variable LANG 7 78 

functions (list) 478 

monetary information 111 

numeric formats 111 

printf 144 

scanf 168 

selecting 176 

_ JJSELOCALES 1 78 

locale.h (header file) 471 
localeconv (function) 111 
localtime (function) 113 
Lock 455, 458 

constructor 455, 458 

destructor 455, 458 
lock (function) 114 
locking (function) 114 
locking.h (header file) 471 
LockRange, TFile member function 438 
locks, file-sharing 114,231 
loglO (complex friend function) 416 
log (complex friend function) 416 
log (function) 115 
loglO (function) 116 
loglOl (function) 116 
logarithm 

base 10 1 16, 416 

complex numbers 416 

natural 115,416 
logl (function) 115 
longjmp (function) 116 

header file 471 
low intensity 117 
LowerBound 

TMArrayAs Vector member function 300 

TMIArray As Vector member function 305 
lowercase 

characters 224, 225 
checking for 105 

conversions 213, 225, 226 

strings 204 
lowvideo, conbuf member function 254 
lowvideo (function) 117 
Jrotl (function) 7 18 
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_lrotr (function) 118 
lsearch (function) 1 18 
lseek (function) 1 19 
ltoa (function) 120 

M 

macros 

argument lists, header file 471 

assert 15, 469 

case conversion 225 

character classification 104, 106, 107 
case 102, 103, 105, 107 
integers 102, 103, 105, 107 
printable characters 105, 106 

character conversion, header file 470 

characters 148 
ASCII conversion 224 

comparing two values 124, 129 

debugging, assert (header file) 469 

defining (header file) 471 

directory manipulation (header file) 470 

file deletion 156 

streaming 291 

toascii 224 

variable argument list 232 
main (function) 3-6 

arguments passed to 3, 243 
example 4 
wildcards 5 

compiled with Pascal calling conventions 6 

declared as C type 6 

global variables and 243 

value returned by 6 
_makepath (function) 120 
malloc (function) 12 1 
malloc.h (header file) 471 
mantissa 77, 131 
math, functions, list 477 
math error handler, user-modifiable 122 
math.h (header file) 471 
math package, floating-point 73 
_matherr (function) 122 
_matherrl (function) 122 
Max 

TDate member function 433 

TTime member function 464 
max (function) 124 



max_waste, string member function 445 

MaxDate, TTime member function 464 

mblen (function) 124 

mbstowcs (function) 125 

mbtowc (function) 125 

mem.h (header file) 471 

memccpy (function) 126 

memchr (function) 126 

memcmp (function) 127 

memcpy (function) 128 

memicmp (function) 128 

memmove (function) 128 

memory 

allocation 

dynamic 22, 76, 121, 155, 194 
errors 425 
functions (list) 478 
_new_handler and 248 
set_new_handler and 248 

checking 478 

copying 126, 128 

freeing 
in heap 76 

functions (list) 476 

header file 469, 471 

initialization 129 

screen segment, copying to 92 

size 194 
memory blocks 

adjusting size in heap 155 

free 97 

filling 99, 100 

initializing 129 

searching 126 
memory .h (header file) 471 
memory management functions 471 
memset (function) 129 
Min 

TDate member function 433 

TTime member function 464 
min (function) 129 
Minute, TTime member function 464 
MinuteGMT, TTime member function 464 
mixing with BCD numbers 414 
mixing with complex numbers 414 
mkdir (function) 130 
mktemp (function) 130 
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mktime (function) 131 

mnemonics, error codes 245, 470 

modes, floating point, rounding 30 

modf (function) 131 

modfl (function) 131 

modulo 70 

Month, TDate member function 433 

MonthName, TDate member function 434 

MonthTy, TDate type definition 431 

MostDerived, TStreamableBase member function 

289 
movetext (function) 132 
_msize (function) 132 
multi-thread libraries 7 
multibyte characters 124 

converting to wchar_t code 125 
multibyte string, converting to a wchar_t array 125 

N 

name, Type_info member function 429 
NameOfDay, TDate member function 434 
NameOfMonth, TDate member function 434 
natural logarithm 115 
new 

TMDoubleListElement operator 346 

TMListElement operator 362 
new files 34, 35, 36, 41,42,161 
new.h (header file) 471 
new_handler (function type) 426 
_new_handler (global variable) 248 
newline character 150 
Next 

TMDequeAs Vector member function 329 

TMDoubleListElement data member 345 

TMListElement data member 362 
nocreate, ios data member 261 
nodes, checking on heap 98 
nonlocal goto 116, 175 
noreplace, ios data member 261 
norm (complex friend function) 416 
normal intensity 133 
normvideo, conbuf member function 254 
normvideo (function) 133 
not operator (!), overloading 287 
number of drives available 89 
numbers 

ASCII, checking for 105 



BCD (binary coded decimal) 411,413 
complex 416 
functions (list) 477 
pseudorandom 153 
random 153 

generating 193 
rounding 22, 69 
turning strings into 1 7 
numeric coprocessors 
control word 30 
exception handler 27, 195 
status word 27, 195 



OBSOLETE.LIB 478 
oct, ios data member 261 
of fsetof (function) 133 
ofpstream class 282 
ofstream (class) 268 
open (function) 134 

header file 470 
Open, TFile member function 438 
open member functions 

filebuf 257 

fpbase 278 

fstream 258 

fstreambase 259 

ifpstream 279 

ifstream 260 

ofpstream 283 

ofstream 269 
openjtnode, ios data member 261 
opendir (function) 135 
openprot, filebuf data member 256 
operating system 

command processor 215 

commands 215 

date and time, setting 195 

environment 

returning data from 90 
variables 57, 189 
accessing 244 

file attributes, shared 50, 163 

path, searching for file in 172, 1 73 

search algorithm 56 

system calls 51, 163 

verify flag 181 
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version number 249, 251 
operator « 

opstream friends 285 

writing prefix /suffix (streamable) 285 
operator ! (), pstream 287 
operator », ipstream friends 282 
operator void *(), pstream member function 287 
opfx, ostream member function 269 
opstream class 283 

friends 285 
OS/2; version 251 
osfx, ostream member function 269 
_osmajor (global variable) 249 
_osminor (global variable) 249 
ostream (class) 269 
ostream_withassign (class) 270 
ostrstream (class) 270 
_osversion (global variable) 249 
out, ios data member 261 
out_waiting, streambuf member function 272 
output 

characters, writing 148 

displaying 74, 141,234 

flushing 64 

formatting 33, 261 

to streams, formatting 74, 141, 234 
overflow member functions 

conbuf 254 

filebuf 257 

strstreambuf 275 
overloaded operators 287 
overwriting files 34 
OwnsElements, TShouldDelete member function 

408 



P_id_type 279, 283 

-p option (Pascal calling conventions), main function 

and 6 
parameter values for locking function 471 
parent process 56, 188 

Pascal calling conventions, compiling main with 6 
passwords 91 

PATH environment variable 57, 189 
paths 

directory 172, 173 

finding 87 



names 

converting 83 
creating 70, 120 
splitting 71, 191 
operating system 172, 173 
pause (suspended execution) 186 
pbase, streambuf member function 273 
pbump, streambuf member function 273 
_pclose (function) 136 
pcount, ostrstream member function 271 
peek, istream member function 266 
PeekHead 

TMDoubleListlmp member function 348 
TMIDoubleListlmp member function 353 
TMInternallListlmp member function 368 
TMListlmp member function 364 
PeekLeft 

TMDequeAsDoubleList member function 335 
TMDequeAs Vector member function 328 
TMIDequeAsDoubleList member function 338 
TMIDequeAs Vector member function 332 
PeekRight 

TMDequeAsDoubleList member function 335 
TMDequeAs Vector member function 328 
TMIDequeAsDoubleList member function 338 
TMIDequeAs Vector member function 332 
PeekTail 

TMDoubleListlmp member function 348 
TMIDoubleListlmp member function 353 
perror (function) 136, 245 

messages generated by 137 
persistent streams, macros 291 
PID (process ID) 92 
_pipe (function) 138 
pointers 

to error messages 200 
file 
initialization 157 
moving 119 
obtaining 65 
resetting 51, 78, 154, 164 
returning 82 

current position of 217 
setting 79, 134, 135, 187 
format specifiers 144, 168 
frame base 117, 176 
stack 117,176 
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stream buffers 287 
pstream 287 

to void, overloading 287 
PointerTypes, pstream data member 286 
polar (complex friend function) 416 
poly (function) 139 
polyl (function) 139 
polynomial equation 139 
Pop 

TMIStackAs Vector member function 387 

TMStackAs Vector member function 384 
_popen (function) 139 
ports 

communications 104 
position 

current 281 
stream 280 

streamable objects 280, 281, 284 
Position, TFile member function 438 
POSIX directory operations 470 
powlO (function) 141 
pow (complex friend function) 416 
pow (complex numbers) 416 
pow (function) 140 
powlOl (function) 141 
powers 

calculating ten to 141 

calculating values to 140 
powl (function) 140 
pptr, streambuf member function 273 
precision 

floating point 30 

format specifiers 142, 143, 146 
precision, ios member function 263 
PRECONDITION macro 420 
PRECONDITIONX macro 421 
prefixes, streamable object's name and 281, 285 
prepend, string member function 445 
Prev 

TMDequeAs Vector member function 329 

TMDoubleListElement data member 345 
Previous, TDate member function 434 
printable characters, checking for 105, 106 
PrintDate, TTime member function 464 
printers, checking for 104 
printf (function) 141 

conversion specifications 142 



format specifiers 141 

input-size modifiers 141 

locale support 144 
printing, error messages 136, 245 
process control, functions (list) 479 
process.h (header file) 471 
process ID 92 
processes 

child 56, 188 

exec... (functions), suffixes 57 

parent 56, 188 

stopping 10 
programs 

loading and running 56 

process ID 92 

signal types 152 

stopping 10, 16 
exit status 23, 58 
request for 152 
suspended execution 186 

termination 426, 427 
pseudorandom numbers 153 
pstream class 286 

punctuation characters, checking for 106 
Push 

TMIStackAs Vector member function 387 

TMStackAs Vector member function 384 
Put 

TMIQueueAsDoubleList member function 378 

TMIQueueAs Vector member function 374 

TMQueueAsDoubleList member function 376 

TMQueue As Vector member function 372 
put, ostream member function 269 
put_at 

string member function 446 

TSubString member function 453 
putback, istream member function 266 
putc (function) 148 
putch (function) 148 
putchar (function) 148 
putenv (function) 149 
PutLeft 

TMDequeAsDoubleList member function 335 

TMDequeAs Vector member function 328 

TMIDequeAsDoubleList member function 338 

TMIDequeAs Vector member function 332 
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PutRight 

TMDequeAsDoubleList member function 335 
TMDequeAs Vector member function 328 
TMIDequeAsDoubleList member function 338 
TMIDequeAs Vector member function 333 

puts (function) 149 

puttext (function) 150 

putw (function) 151 



Q 



qsort (function) 151 
quicksort algorithm 151 
quotients 110 



raise (function) 152 

header file 471 
raise member function, xmsg 430 
raise member functions 

xalloc 429 
rand (function) 153 
random (function) 153 
random number generator 153 

initialization 153, 193 
random numbers 153 
randomize (function) 153 
range facility shortcut 169 
rdbuf member functions 

constream 255 

fpbase 278 

fstream 258 

fstreambase 259 

ifpstream 279 

ifstream 260 

ios 263 

ofpstream 283 

ofstream 269 

pstream 287 

strstreambase 274 
rdstate 

ios member function 263 

pstream member function 287 
Read 

TFile member function 438 

TStreamer member function 290 
read (function) 154 



read, istream member function 266 
_dos_read (function) 50 
read error 63 

read_file, string member function 446 
read_line, string member function 446 
read_string, string member function 446 
read_to_delim, string member function 446 
read_token, string member function 446 
read /write flags 134, 187 
readByte, ipstream member function 280 
readBytes, ipstream member function 280 
readData, ipstream member function 281 
readdir (function) 155 
readPrefix, ipstream member function 281 
readString, ipstream member function 280 
readSuffix, ipstream member function 281 
readVersion, ipstream member function 281 
readWordl6, ipstream member function 280 
readWord32, ipstream member function 280 
readWord, ipstream member function 280 
real friend functions 
bed 413 
complex 416 
realloc (function) 155 
Reallocate 

TMArray As Vector member function 300 
TMIArrayAs Vector member function 305 
records, sequential 1 10 
RefDate, TTime data member 464 
RegClassName 289 
register variables, as task states 117 
registerObject 

ipstream member function 280 
opstream member function 284 
registerVB, opstream member function 284 
registration types 289 
remainder 40, 70,110 
remove (function) 156 
remove, string member function 446 
Remove, TFile member function 438 
RemoveEntry 

TMArray As Vector member function 300 
TMIArrayAs Vector member function 305 
rename (function) 157 
Rename, TFile member function 439 
replace, string member function 447 
request for program termination 152 
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requested member function, xalloc 429 
reserve, string member function 447 
Resize 

TMIVectorlmp member function 401 

TMVectorlmp member function 392 
resize, string member function 447 
resize_increment, string member function 447 
Restart 

TBinarySearchTreelteratorlmp member function 

324 

TIBinarySearchTreelteratorlmp member 

function 326 

TMArrayVectorlterator member function 301 

TMDequeAsVectorlterator member function 

330 

TMDictionaryAsHashTablelterator member 

function 341 

TMDoubleListlteratorlmp member function 349 

TMHashTablelteratorlmp member function 358 

TMIArrayAsVectorlterator member function 

306 

TMIDictionaryAsHashTablelterator member 

function 344 

TMIDoubleListlteratorlmp member function 

354 

TMIHashTablelteratorlmp member function 

360 

TMIListlteratorlmp member function 368 

TMIVectorlteratorlmp member function 402 

TMListlteratorlmp member function 365 

TMVectorlteratorlmp member function 394 
restoring screen 150 
Resume, TThread member function 460 
rewind (function) 157 
rewinddir (function) 158 
rfind, string member function 446 
right, ios data member 261 
Right, TMDequeAs Vector data member 329 
rmdir (function) 158 
rmtmp (function) 159 
rotation, bit 

long integer 118 

unsigned char 37 

unsigned integer 159 
_rotl (function) 759 
_rotr (function) 159 
rounding 22, 69 



banker's 412 

modes, floating point 30 
_rtl_chmod (function) 159 
_rtl_close (function) 160 
_rtl_creat (function) 161 
_rtl_heapwalk (function) 161 
_rtl_open (function) 162 
_rtl_write (function) 164 

rtti type (Type_info class) 428 

run-time library 

functions by category 472 

source code, licensing 469 

s 

SJREAD 229 

SJWRITE 229 

sbumpc, streambuf member function 272 

scanf (function) 165 

format specifiers 165 

locale support 168 

termination 171 
conditions 1 72 
scientific, ios data member 261 
scratch files 

naming 217, 223 

opening 223 
screens 

clearing 29 

copying text from 132 

displaying strings 33 

echoing to 85, 86 

formatting output to 33 

modes, restoring 150 

saving 93 

segment, copying to memory 92 

writing characters to 148 
scrolling 251 
search.h (header file) 471 
search key 118 
_searchenv (function) 1 72 
searches 

appending and 1 18 

binary 20 

block, for characters 126 

header file 472 

linear 110,118 
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operating system 
algorithms 56 
path, for file 172, 173 

string 
for character 196 
for tokens 211 
searchpath (function) 1 73 
_searchstr (function) 1 73 
Second, TTime member function 464 
Seconds, TTime member function 464 
security, passwords 91 
seed number 193 
Seek, TFile member function 439 
seek_dir, ios data member 260 
seekg 

ipstream member function 280 

istream member function 266 
seekoff member functions 

filebuf 257 

streambuf 272 

strstreambuf 275 
seekp 

opstream member function 284 

ostream member function 269, 270 
seekpos, streambuf member function 272 
SeekToBegin, TFile member function 439 
SeekToEnd, TFile member function 439 
segments 

scanning for characters in strings 209 

screen, copying to memory 92 
sequential records 1 10 

set_case_sensitive, string member function 447 
set_new_handler (function) 248, 425 
set_paranoid_check, string member function 447 
set_terminate (function) 426 
set_unexpected (function) 427 
setb, streambuf member function 273 
setbuf (function) 1 74 
setbuf member functions 

filebuf 257 

fpbase 278 

fstreambase 259 

streambuf 272 

strstreambuf 275 
setcursortype, conbuf member function 254 
setcursortype (function) 1 75 



SetData 

TMArray As Vector member function 300 

TMIArrayAsVector member function 306 
setdate (function) 45 
setdisk (function) 89 
setf, ios member function 263 

constants used with 260 
setftime (function) 90 
setg, streambuf member function 274 
setjmp (function) 1 75 

header file 471 
setjmp.h (header file) 471 
setlocale (function) 1 76 
setmode (function) 1 79 
setp, streambuf member function 274 
SetPrintOption, TDate member function 434 
SetPriority, TThread member function 460 
setstate 

ios member function 264 

pstream member function 288 
SetStatus, TFile member function 439 
settime (function) 94 
setting file read/write permission 228 
setvbuf (function) 180 
setverify (function) 181 
sgetc, streambuf member function 272 
sgetn, streambuf member function 272 
share. h (header file) 471 

ShouldTerminate, TThread member function 461 
showbase, ios data member 261 
showpoint, ios data member 261 
showpos, ios data member 261 
signal (function) 182 

header file 471 
use in multi-thread program 8 
signal.h (header file) 471 
signals 

handlers 152, 182 
returning from 184 
user-specified 182 

program 152 
sin (complex friend function) 417 
sin (function) 185 
sine 185 

complex numbers 417 

hyperbolic 185 

inverse 14 
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sinh (complex friend function) 41 7 

sinh (complex numbers) 417 

sinh (function) 185 

sinhl (function) 185 

sinl (function) 185 

size 

file 26, 66 
skipjwhitespace, string member function 447 
skipws, ios data member 261 
sleep (function) 186 
snextc, streambuf member function 272 
software signals 152 
sopen (function) 186 
sorts, quick 151 

source code, run-time library, licensing 469 
space on disk, finding 46, 88 
spawn... 

(functions) file handles 468 
spawn... (functions), suffixes 189 
spawnl (function) 188 
spawnle (function) 188 
spawnlp (function) 188 
spawnlpe (function) 188 
spawnv (function) 188 
spawnve (function) 188 
spawnvp (function) 188 
spawnvpe (function) 188 
_splitpath (function) 19 1 
sprintf (function) 192 

format specifiers 141, 192 
sputbackc, streambuf member function 272 
sputc, streambuf member function 272 
spurn, streambuf member function 272 
sqrt (complex friend function) 417 
sqrt (function) 192 
sqrtl (function) 192 
square root 192 

complex numbers 417 
SqueezeEntry 

TMIArray As Vector member function 306 
srand (function) 193 
sscanf (function) 193 

format specifiers 165 
stack 

pointer, as task states 117, 176 

size 194 
stackavail (function) 194 



standard time 38, 40, 83, 95 

start, TSubString member function 453 

Start, TThread member function 460 

stat (function) 81 

stat structure 81 

state 

ios data member 262 

pstream data member 287 

read current pstream 287 

set current pstream 288 
_status87 (function) 194 
Status, TThread data member 459 
status word 

floating-point 26, 194 

numeric coprocessors 27, 195 
stdargs.h (header file) 471 
stdaux 61 

stddef.h (header file) 471 
stderr 61, 76 
stderr (header file) 471 
stdin 61, 76 

buffers and 174 

reading 
characters from 65, 86 
input from 165, 235 
strings from 92 
stdin (header file) 471 
stdio, ios data member 261 
stdio.h (header file) 471 
stdiostr.h (header file) 471 
stdlib.h (header file) 472 
stdout 61, 76 

buffers and 174 

writing 

characters to 74, 148 
formatted output to 141,234 
strings to 149 
stdout (header file) 471 
stdprn 61 

stime (function) 195 
storage, invalid access 152 
stossc, streambuf member function 272 
stpcpy (function) 195 
str member functions 

ostrstream 271 

strstream 276 

strstreambuf 275 
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strcat (function) 196 
strchr (function) 196 
strcmp (function) 197 
strcmpi (function) 197 
strcoll (function) 198 
strcpy (function) 198 
strcspn (function) 1 99 
_strdate (function) 199 
strdup (function) 199 
streamable classes 

base class 286 

BUILDER typedef and 289 

creating 288, 289 

reading 279 
strings 280 

registering 289 

TStreamableBase 288 

TStreamableClass 289 

writing 283 
streamable objects 

basic operations 278 

finding 279, 283 

flushing 283 

position within 280, 281, 284 

reading 278, 281 
current position 280 

writing 278, 282 
StreamableName, TStreamer member function 290 
streambuf (class) 271 
streaming macros 291 

DECLARE_ABSTRACT_STREAMABLE 292 

DECLARE_ABSTRACT_STREAMER 292 

DECLARE_CASTABLE 293 

DECLARE_STREAMABLE 291 

DECLARE_STREAMABLE_CTOR 293 

DECLARE_STREAMABLE_FROM_BASE 29 1 

DECLARE_STREAMABLE_OPS 293 

DECLARE_STREAMER 292 

DECLARE_STREAMER_FROM_BASE 292 

IMPLEMENT_ABSTRACT_STREAMABLE 295 

IMPLEMENT_CASTABLE_ID 294 

IMPLEMENT_STREAMABLE 293 

IMPLEMENT_STREAMABLE_CLASS 294 

IMPLEMENT_STREAMABLE_CTOR 294 

IMPLEMENT_STREAMABLE_POINTER 294 

IMPLEMENT STREAMER 295 



streams 

buffer, pointer to 287 

closing 61, 76 

end of 286 

error and end-of-file indicators 27, 63 

flushing 64, 69, 283 

formatting input from 77, 234, 236 

stdin 165, 235 
header file 471 
hierarchy 277 
I/O 63, 73, 77, 80 

pushing character onto 229 
initializing 288 
linking file handles to 62 
macros 291 
opening 72, 76, 79 
pointers 

file 78, 79 

initialization 157 
reading 

characters from 64, 85 

data from 75 

errors 286 

input from 77, 234, 236 
stdin 165 

integers from 95 

strings from 65 
reading and writing, errors 286 
registering 289 
replacing 76 
state 286 
stdaux 61 
stderr 61, 76 
stdprn 61 

terminated input 172 
tied 263 

unbuffered 174, 180 
writing 69, 84 

characters to 74, 148 

errors 286 

formatted output to 74, 141, 233 
stdout 234 

integers to 151 

strings to 75, 149 
writing to 284, 285 
_strerror (function) 200 
strerror (function) 200 
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strftime (function) 201 
stricmp (function) 203 
string 439 

!= operator 450 

() operator 449 

+= operator 449 

<= operator 451 

== operator 450 

>= operator 451 

» operator 451 

[] operator 449 

+ operator 449 

< operator 450 

= operator 449 

> operator 451 

append member function 44 1 

assign member function 44 1 

assignment operator 449 

c_str member function 442 

compare member function 44 1 

concatentation operator 449 

copy member function 442 

cow member function 448 

find_first_not_of member function 443 

find_first_of member function 443 

find_last_not_of member function 444 

find_last_of member function 444 

find member function 442 

get_case_sensitive_flag member function 444 

get_initial_capacity member function 444 

get_max_waste member function 444 

get_paranoid_check member function 444 

get_resize_increment member function 444 

get_skipwhitespace_flag member function 445 

hash member function 445 

initial_capacity member function 445 

isjnull member function 445 

length member function 445 

max_waste member function 445 

prepend member function 445 

read_file member function 446 

read_line member function 446 

read_string member function 446 

read_to_delim member function 446 

read_token member function 446 

replace member function 447 

reserve member function 447 



resize_increment member function 447 
resize member function 447 
rfind member function 446 
set_case_sensitive member function 447 
set_paranoid_check member function 447 
skip_whitespace member function 447 
strip member function 447 
substr member function 448 
substring member function 448 
to_lower member function 448 
to_upper member function 448 
string.h (header file) 472 
strings 

appending 196 

parts of 204 
array allocation 280 
changing 213 
comparing 127, 197, 198 

ignoring case 128, 197, 203 

parts of 205 
ignoring case 205, 206 
concatenating 196, 204 
copying 195, 198 

new location 199 

truncating or padding 206 
displaying 33, 143 
duplicating 199 
format specifiers 143, 167 
formatting 192,201,236 
functions 

with multiple prototypes 472 
functions (list) 476 
header file 472 
initialization 207, 208 
length, calculating 203 
lowercase 204 
reading 167, 280 

formatting and 193 

from console 23 

from streams 65, 92 
reversing 208 
searching 

for character 196 
in set 207 

last occurrence of 207 
not in set 199 

for segment in set 209 
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for substring 209 

for tokens 211 
space allocation 280 
transforming 213 
uppercase 213 
writing 

formatted output to 192, 236 

to current environment 149 

to screen 33 

to stdout 149 

to streams 75, 283 
strip, string member function 447 
StripType, string type definition 439 
strlen (function) 203 
strlwr (function) 204 
strncat (function) 204 
strncmp (function) 205 
strncmpi (function) 205 
strncpy (function) 206 
strnicmp (function) 206 
strnset (function) 207 
strpbrk (function) 207 
strrchr (function) 207 
strrev (function) 208 
strset (function) 208 
strspn (function) 209 
strstr (function) 209 
strstrea.h (header file) 472 
strstream (class) 276 
strstreambase (class) 274 
strstreambuf (class) 274 
_strtime (function) 209 
strtod (function) 210 
strtok (function) 21 1 
strtol (function) 21 1 
_strtold (function) 210 
strtoul (function) 213 
struct heap info 101 
structures 
stat 81 
strupr (function) 213 
strxfrm (function) 213 
substr, string member function 448 
substring, string member function 448 
substrings, scanning for 209 
suffixes 
exec... 57 



spawn... 189 

streamable object's name and 281, 285 
support for variable-argument funtions 472 
Suspend, TThread member function 460 
suspended execution, program 186 
swab (function) 215 
swapping bytes 215 
sync member functions 

filebuf 257 

strstreambuf 275 
sync_with_stdio, ios member function 263 
sys\stat.h (header file) 472 
sys\types.h (header file) 472 
_sys_errlist (global variable) 245 
_sys_nerr (global variable) 245 
system 

buffers 61 

commands, issuing 215 

error messages 136, 245 
system (function) 215 



T constructor 

TBinarySearchTreelteratorlmp 324, 326 

TMDictionaryAsHashTablelterator 341, 343, 

344 

TMIHashTablelmp 359 
tables, searching 20, 118 
Tail 

TMDoubleList data member 348 

TMListlmp data member 364 
tan (complex friend function) 4 1 7 
tan (function) 216 
tangent 21 6, 417 

complex numbers 417 

hyperbolic 216 

inverse 15, 16 
tanh (complex friend function) 417 
tanh (function) 216 
tanhl (function) 216 
tanl (function) 216 
TArrayAsVector 302 

constructor 302 
TArrayAsVectorlterator 302 

constructor 302 
task states 

defined 117,176 
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register variables 117 
TBag As Vector 319 

constructor 319 
TBag AsVectorltera tor 319 

constructor 319 
TBinarySearchTreelmp 322 
TBinarySearchTreelteratorlmp 323 
TCriticalSection 454 

constructor 455 

destructor 455 
TCVectorlmp 397 

constructor 397 
TCVectorlteratorlmp 398 
TDate 431 

constructor 432 
TDDAssociation372 

constructor 312 
TDeque constructor 33 1 
TDequeAsDoubleList 336 
TDequeAsDoubleListlterator 336 

constructor 336 
TDequeAs Vector 330 

constructor 330 
TDequeAs Vectorlterator 330 
TDIAssociation 313 

constructor 313 
TDictionary 345 
TDictionaryAsHashTable 347 

constructor 342 
TDictionaryAsHashTablelterator 342 

constructor 342 
TDictionarylterator 345 

constructor 345 
TDoubleListlteratorlmp 350 

constructor 350 
tell (function) 217 
tellg 

ipstream member function 281 

istream member function 267 
tellp 

opstream member function 284 

ostream member function 270 
template (file names) 130 
tempnam (function) 217 
temporary files 

naming 217, 223 

opening 223 



removing 159 
terminals, checking for 104 
terminate (function) 427 
Terminate, TThread member function 460 
TerminateAndWait, TThread member function 

460 
terminating 

input from streams 1 72 
software signals 152 
termination function 16 
testing conditions 15 
text 

attributes 218, 219, 220 
background color, setting 218,219 
colors 220 
copying 
from one screen rectangle to another 132 
to memory 92 
to screen 150 
intensity 
high 101 
low 117 
normal 133 
modes (screens) 150, 222, 240 
character color 2 1 8, 220 
coordinates 93 
copying to memory 92 
video information 93 
text files 
creat and 34 
creattemp and 36 
_dos_read and 51 
fdopen and 62 
fopen and 73 
freopen and 76 
_fsopen and 80 
_rtl_read and 163 
reading 154 
setting 179 
mode 62, 73, 76, 80, 248 
textattr (conbuf member functions) 254 
textattr (function) 218 

textbackground (conbuf member function) 254 
textbackground (function) 219 
textcolor (conbuf member function) 254 
textcolor (function) 220 
textmode (function) 222 
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textmode member functions 

conbuf 254 

constream 255 
TFile 436 

constructor 437 
TFileStatus 436 
THashTablelmp 358 

constructor 358 
THashTablelteratorlmp 359 

constructor 359 
thread 

locking and protecting 455 
thread ID 249 
_threadid (global variable) 249 

throwExceptionName (global variable) 250 

throwFileName (global variable) 250 

throwLineNumber (global variable) 250 

TIArrayAsVector 307 

constructor 307 
TIArrayAsVectorlterator 307 

constructor 308 
TIBagAsVector 322 

constructor 322 
TIBagAsVectorlterator 322 

constructor 322 
TIBinarySearchTreelmp 324 
TIBinarySearchTreelteratorlmp 326 
TICVectorImp 405 

constructor 405 
TID Association 315 

constructor 315 
TIDequeAsDoubleList 339 
TIDequeAsDoubleListlterator 339 

constructor 339 
TIDequeAs Vector 333 

constructor 333 
TIDequeAs Vectorlterator 334 

constructor 334 
TIDictionaryAsHashTable 344 
TIDictionaryAsHashTablelterator 344 

constructor 345 
TIDoubleListlmp 354 
TIDoubleListlteratorlmp 355 

constructor 355 
tie, ios member function 263 
tied streams 263 
TIHashTablelmp 361 



TIHashTablelteratorlmp 361 

constructor 361 
TIIAssociation 316 

constructor 317 
TIListlteratorlmp 369 

constructor 369 
time 

delays in program execution 186 

difference between two 40 

elapsed 27, 40 
returning 223 

file 48, 90 

formatting 201 

functions (list) 480 

global variables 227, 244, 250 

system 13, 38, 83, 95 
converting from DOS to UNIX 53 
converting from UNIX to DOS 230 
local 113 
returning 49, 94 
setting 49, 94, 195 
time (function) 223 
time.h (header file) 472 
time zones 83, 95 

arrays 250 

differences between 40 

global variables 244, 250 

setting 38, 227 
_timezone (global variable) 250 

setting value of 227 
TIQueueAsDoubleList 379 
TIQueueAsDoubleListlterator 379 

constructor 379 
TIQueueAs Vector 375 

constructor 375 
TIQueueAs Vectorlterator 375 

constructor 375 
TISArrayAsVector 309 

constructor 310 
TIS Array As Vectorlterator 310 

constructor 310 
TISDoubleListlmp 356 
TISDoubleListlteratorlmp 356 

constructor 356 
TISetAs Vector 382 
TISetAs Vectorlterator 382 

constructor 383 



Index 



513 



TIStackAsList 390 
TIStackAsListlterator 390 

constructor 390 
TIStackAs Vector 388 

constructor 388 
TIStackAs Vectorlterator 388 
TISVectorImp 407 

constructor 407 
TlVectorlmp 403 

constructor 403 
TMArrayAs Vector 297 

constructor 298 
TMArrayAs Vectorlterator 301 

constructor 301 
TMBagAsVector377 

constructor 317 
TMBag As Vectorlterator 318 

constructor 319 
TMCVectorlmp 395 
TMCVectorlteratorlmp 397 
TMDDAssociation 310 

constructor 3 11 
TMDequeAsDoubleList 334 
TMDequeAsDoubleListlterator 336 

constructor 336 
TMDequeAs Vector 327 

constructor 327 
TMDequeAs Vectorlterator 329 

constructor 329 
TMDIAssociation 312 

constructor 312 
TMDictionaryAsHashTable 339 
TMDictionaryAsHashTablelterator 340 
TMDictionayAsHashTable 

constructor 340 
TMDoubleListElement 345 

constructor 346 
TMDoubleListlmp 346, 349 
TMDoubleListlteratorlmp 348 

constructor 348 
TMHashTablelmp 356 

constructor 356 
TMHashTablelteratorlmp 357 

constructor 357 
TMIArrayAsVector 302 

constructor 303 
TMIArrayAs Vectorlterator 306 



constructor 306 
TMIBagAs Vector 319 

constructor 320 
TMIBagAs Vectorlterator 321 

constructor 321 
TMID Association 314 

constructor 314 
TMIDequeAsDoubleList 336 
TMIDequeAsDoubleListlterator 338 

constructor 339 
TMIDeque As Vector 331 

constructor 331 
TMIDequeAs Vectorlterator 333 

constructor 333 
TMIDictionaryAsHashTable 342 

constructor 342 
TMIDictionaryAsHashTablelterator 343 
TMIDoubleListlmp 352 
TMIDoubleListlteratorlmp 354 

constructor 354 
TMIHashTablelmp 359 

constructor 361 
TMIHashTablelteratorlmp 360 

constructor 360 
TMIIAssociation 315 

constructor 316 
TMIQueueAsDoubleList 377 
TMIQueueAsDoubleListlterator 379 

constructor 379 
TMIQueueAsVector 373 

constructor 373 
TMIQueueAsVectorlterator 374 

constructor 375 
TMISArrayAsVector 310 

constructor 310 
TMISDoubleListlmp 355 
TMISDoubleListlteratorlmp 355 

constructor 355 
TMISet As Vector 381 

constructor 381 
TMISetAs Vectorlterator 382 

constructor 382 
TMIStackAsList 389 
TMIStackAsListlterator 390 

constructor 390 
TMIStackAsVector 386 
TMIStackAsVectorlterator 387 
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constructor 388 
TMIVectorlmp 400 
tmpfile (function) 223 
tmpnam (function) 223 
TMQueueAsDoubleList 375 
TMQueueAsDoubleListlterator 377 

constructor 377 
TMQueueAsVector 371 

constructor 371 
TMQueueAsVectorlterator 372 

constructor 372 
TMSArrayAsVector 308 

constructor 308 
TMSArrayAsVectorlterator 

constructor 308 
TMSDoubleListlmp 350 
TMSDoubleListlteratorlmp 351 

constructor 351 
TMSetAs Vector 380 

constructor 380 
TMSetAsVectorlterator 380 

constructor 380 
TMStackAsList 388 
TMStackAsListlterator 389 
TMStackAs Vector 

constructor 383 
TMStackAs Vectorlterator 385 

constructor 385 
TMSVectorlmp 398 
TMSVectorlteratorlmp 398 
TMutex 455 

constructor 456 

destructor 456 

HMTX operator 456 
TMutex: :Lock 456 

constructor 456, 457 
TMVectorlmp 391 
to_lower 

global string function 452 

string member function 448 

TSubString member function 453 
to_upper 

global string function 452 

string member function 448 

TSubString member function 453 
toascii (function) 224 
tokens, searching for in string 21 1 



_tolower (function) 224 
tolower (function) 225 
Top 

TMCVectorlmp member function 397 

TMIStackAs Vector member function 387 

TMIVectorlmp member function 401 

TMStackAs Vector member function 384 

TMVectorlmp member function 393 
_toupper (function) 225 
toupper (function) 226 
TQueue 379 

TQueueAsDoubleList 377 
TQueueAsDoubleListlterator 377 

constructor 377 
TQueueAs Vector 373 

constructor 373 
TQueue As Vector Iterator 373 

constructor 373 
TQueuelterator 380 

TRACE debugging symbol 419 

TRACE macro 420 
TRACEX macro 421 
translation mode 34, 36, 248 
triangles, hypotenuse 101 
trigonometric functions 

arc cosine 12 

arc sine 14 

arctangent 15, 16 

cosine 31 
hyperbolic 31 
inverse 12 

hyperbolic tangent 216 

sine 185 
hyperbolic 185 
inverse 14 

tangent 216 
hyperbolic 216 
inverse 15, 16 
trunc, ios data member 261 
truncate (function) 226 
TSArray 308 
TSArrayAs Vector 309 

constructor 309 
TSArray As Vectorlterator 308, 309 

constructor 309 
TSArraylterator 309 
TSDoubleListlmp 351 
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TSDoubleListlteratorlmp 351 

constructor 351 
TSet 383 

constructor 381, 382 
TSet As Vector 381 
TSetAsVectorlterator 381 

constructor 381 
TSetlterator 383 
TShouldDelete 408 

constructor 408 
TSListlteratorlmp 366 
TStack 390 
TStackAsList 389 
TStackAsListlterator 389 
TStackAs Vector 385 

constructor 385 
TStackAs Vectorlterator 385 

constructor 386 
TStacklterator 391 
TStreamableBase 288 

CastablelD member function 288 

destructor 288 

FindBase member function 288 

MostDerived member function 289 
TStreamableClass 289 

DELTA macro 289 

friends of 290 
TStreamer 290 

constructor 290 

GetObject member function 290 

Read member function 290 

StreamableName member function 290 

Write member function 291 
TString 

constructor 440 

destructor 44 1 
TSubString 452 

() operator 454 

assert_element member function 453 

get_at member function 452 

is_null member function 453 

length member function 453 

put_at member function 453 

start member function 453 

to_lower member function 453 

to_upper member function 453 
TSVectorlmp 399 



constructor 399 
TSVectorlteratorlmp 399 
TSync 457 

- operator 458 
constructor 457 

TThread 458 
= operator 461 
constructor 460 
destructor 460 

GetPriority member function 460 
GetStatus member function 460 
Resume member function 460 
SetPriority member function 460 
ShouldTerminate member function 461 
Start member function 460 
Status data member 459 
Suspend member function 460 
Terminate member function 460 
TerminateAndWait member function 460 
WaitForExit member function 461 

TThreadError 461 

ErrorType data member 461 
GetErrorType member function 462 

TTime 462 

!= operator 465 
++ operator 465 
+= operator 465 

- operator 465 
-= operator 465 
« operator 465 
<= operator 465 
== operator 465 
>= operator 465 
» operator 466 
+ operator 465 

- operator 465 
< operator 465 
> operator 465 

AssertDate member function 464 
AsString member function 463 
BeginDST member function 463 
Between member function 463 
CompareTo member function 463 
constructor 463 
EndDST member function 463 
Hash member function 463 
Hour member function 463 
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HourGMT member function 463 

IsDST member function 463 

Is Valid member function 464 

Max member function 464 

MaxDate data member 464 

Min member function 464 

Minute member function 464 

MinuteGMT member function 464 

PrintDate member function 464 

RefDate data member 464 

Second member function 464 

Seconds member function 464 
TVectorlmp 394 

constructor 395 
TVectorlteratorlmp 395 

constructor 395 
type checking, device 104 
Type_id, TStreamable base typedef 288 
Type_info class 428 
typeid operator (Type_info class) 428 
typeinfo.h (header file) 472 
_tzname (global variable) 250 

setting value of 227 
tzset (function) 227 

u 

U.S. date formats 32 

ultoa (function) 228 

umask (function) 228 

unbuffered, streambuf member function 274 

unbuffered streams 174, 180 

undefined external 478 

underflow member functions 

filebuf 257 

strstreambuf 276 
unexpected (function) 429 
ungetc (function) 229 
ungetch (function) 229 
unitbuf, ios data member 261 
UNIX 

constants, header file 472 

date and time 
converting DOS to 53 
converting to DOS format 230 
unixtodos (function) 230 
unlink (function) 230 
unlock (function) 231 



UnlockRange, TFile member function 439 
unsetf, ios member function 263 
UpperBound 

TMArrayAs Vector member function 300 

TMIArrayAsVector member function 305 
uppercase 

characters 107, 225, 226 

checking for 107 

conversions 204, 224, 225 

strings 213 
uppercase, ios data member 261 
USELOCALES__ 

international support 
API, enabling 476 
macro 178 
user-defined comparison function 151 
user-defined formatting flags 264 
user hook 122 

user-modifiable math error handlers 122 
user-specified signal handlers 182 
utime (function) 231 
utime.h (header file) 472 

V 

va_arg (function) 232 

va_arg (variable argument macro) 232 

va_end (function) 232 

va_list (variable argument macro) 232 

va_start (function) 232 

va_start (variable argument macro) 232 

valid_element, string member function 449 

valid_index, string member function 449 

Value 

TMDD Association member function 31 1 
TMDI Association member function 313 
TMID Association member function 315 
TMIIAssociation member function 316 

ValueData, TMID Association data member 314 

values 

calculating powers to 140, 141 
comparing 124, 129 

values.h (header file) 472 

varargs.h (header file) 472 

variables 

argument list 232 

conversion specifications and 142 

environment 57, 189, 244 
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COMSPEC275 

register 117 
verify flag (DOS) 94 
verify the heap 100 
version numbers 

DOS 249 

operating system 251 

OS/2 249 
_version (global variable) 25 1 
vfprintf (function) 233 

format specifiers 141 

variable argument list 232 
vfscanf (function) 234 

format specifiers 165 

variable argument list 232 
video 

checking for 104 

information, text mode 93 
void *(), pstream operator 287 
vprintf (function) 234 

format specifiers 141 

variable argument list 232 
vscanf (function) 235 

format specifiers 165 

variable argument list 232 
vsprintf (function) 236 

format specifiers 141 

variable argument list 232 
vsscanf (function) 236 

format specifiers 165 

variable argument list 232 

w 

wait (function) 237 

WaitForExit TThread member function 461 

_ _WARN debugging symbol 419 

WARN macro 420 

WARNX macro 421 

wcstombs (function) 238 

wctomb (function) 238 

WeekDay, TDate member function 434 

wherex, conbuf member function 254 

wherex (function) 239 

wherey, conbuf member function 254 

wherey (function) 239 

whitespace, checking for 107 

why member function, xmsg 430 



width, ios member function 264 
WILDARGS.OBJ 5 
wildcards, expansion 5 

by default 6 

from the IDE 6 
window (function) 240 
window member functions 

conbuf 254 

constream 255 
windows 

functions (list) 480 

scrolling 251 

text 

cursor position 96, 239 
defining 240 
deleting lines in 29, 40 
inserting blank lines in 102 
words 

floating-point control 30 

writing to streams 284 
Write 

TFile member function 439 

TStreamer member function 291 
write (function) 240 
write, ostream member function 270 
write error 63 

writeByte, opstream member function 284 
writeBytes, opstream member function 284 
writeData, opstream member function 285 
writeObjectPointer, opstream member function 

284 
writePrefix, opstream member function 285 
writeString, opstream member function 284 
writeSuffix, opstream member function 285 
writeWordl6, opstream member function 284 
write Word32, opstream member function 284 
writeWord, opstream member function 284 



x_fill, ios data member 261 
x_flags, ios data member 261 
x_precision, ios data member 261 
x_tie, ios data member 262 
x_width, ios data member 262 
xalloc (class) 429 
xalloc, ios member function 264 
xmsg (class) 430 
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ear, TDate member function 434 
earTy, TDate type definition 431 



z 

Zero 

TMIVectorlmp member function 402 
TMVectorlmp member function 393 

ZeroBase 

TMArray As Vector member function 300 
TMIArray As Vector member function 306 
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